Skip to content

Docs: worker platforms and Windows setup #1692

Closed
1 of 1 issue completed
Closed

Description

@V3RON

Request: #1071

Problem

The website doesn't say which platforms a worker supports, and has no Windows setup steps. Cover: Windows supports Android only (iOS needs macOS); Android SDK discovery (ANDROID_HOME, default %LOCALAPPDATA%\Android\Sdk); the daemon endpoint is a named pipe; running the daemon as a service, once it is supported.

Today several pages say the CLI, Android emulators and the gateway run on "macOS or Linux", so a Windows user reads that Simlock is not for them, although an Android worker runs end to end on Windows on main.

Who it is for

A developer or operator with a Windows 11 PC who wants to run Android emulators for their agents on it, alone or as a worker behind a gateway. They know Windows and PowerShell; they may not know the Android SDK's command-line setup.

Outcome

  • Every page that says where Simlock runs says the same thing, Windows included: Android emulators and the gateway run on Windows; iOS needs macOS.
  • A Windows user follows one page, "Set up a Windows worker", from a fresh Windows 11 to a first Android lease, with PowerShell commands that work as written.
  • That page says what works on Windows today, what does not (iOS, start at login), and what nobody has checked yet (physical Android phones).

How it works for the user

flowchart TD
  A[Reads Requirements] --> B["Table: Windows column says Android emulators and gateway: yes, iOS: no"]
  B --> C[Opens 'Set up a Windows worker']
  C --> D[Installs Node, simlock, Android SDK, JDK; turns on Windows Hypervisor Platform]
  D --> E[simlock doctor]
  E -->|a line per missing tool| D
  E -->|no findings| F[simlock lease --platform android]
  F -->|emulator does not boot| G["Page: check emulator -accel-check"]
  G --> D
  F --> H[simlock adb, simlock release]
  H --> I{Wants start at login?}
  I --> J["Page: not on Windows yet; start it from a terminal"]
Loading

Before, on the Requirements page:

| The `simlock` CLI | macOS or Linux | Node.js 22.13 or later |
| Android emulators | macOS or Linux | ... |

After (the exact wording is the task's; the table also gains the three rows of Examples it lacks today: physical iPhone, physical Android phone, start at login):

| The `simlock` CLI      | macOS, Linux or Windows | Node.js 22.13 or later |
| iOS simulators         | macOS only              | ...                    |
| Android emulators      | macOS, Linux or Windows | ... On Windows also Windows Hypervisor Platform. |
| A gateway              | macOS, Linux or Windows | ...                    |

The Windows page's session, in PowerShell:

PS> Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
PS> npm i -g simlock
PS> simlock doctor
{"findings":[],"sources":[]}
PS> simlock config set downloads.acceptAndroidLicenses true
PS> simlock daemon stop
PS> simlock component install android 35
PS> simlock lease --platform android --detach
PS> simlock adb -s emulator-5586 shell getprop ro.build.version.release
15
PS> simlock release <lease-id>

Examples

What each platform row of the Requirements table says:

Row Today After
The simlock CLI macOS or Linux macOS, Linux or Windows
iOS simulators macOS only macOS only
Android emulators macOS or Linux macOS, Linux or Windows
A gateway macOS or Linux macOS, Linux or Windows
Physical iPhone (Use physical devices section: a Mac) a Mac
Physical Android phone (no OS named) no OS named, plus: not checked on Windows yet
Start at login (daemon install) macOS and Linux (Run the daemon page) macOS and Linux; not on Windows yet

What could go wrong

  • A step on the Windows page fails on a fresh machine because the session's machine had something set up already. Likely enough that the steps are run on the Windows machine before the PR merges.
  • A page still says "macOS or Linux" and contradicts the Windows page. Low: the task lists every such line.
  • The page promises something on Windows that breaks later, because no CI runs on Windows yet (CI: run the tests on Windows #1070).
  • A JSON value on the command line, such as the gateway join, is mangled by Windows PowerShell 5.1 unless its quotes are escaped. Likely for anyone who copies a macOS example; the Windows page says how to write it.

Words used

  • worker: the machine that owns and runs the devices, e.g. a Windows PC running Android emulators.
  • gateway: one daemon that sends lease requests from agents to several workers; it runs no devices.
  • Windows Hypervisor Platform (WHPX): the Windows feature the Android emulator uses to run fast; without it the emulator does not start.
  • named pipe: how the CLI talks to the daemon on Windows, in place of the daemon.sock file on macOS and Linux, e.g. \\.\pipe\simlock-1a2b3c4d5e6f7a8b.

Non-goals

Completion conditions

  • No website page or README line says the CLI, Android emulators or the gateway run on "macOS or Linux" only.
  • The Requirements table has a Windows answer on every row, and links to the Windows page.
  • On a Windows 11 machine, every command on the Windows page runs as written in PowerShell, and the page's flow ends with a granted Android lease, a simlock adb command answered and the lease released.
  • The Windows page names what works on Windows, what does not, and what is not checked, and each "works" item was seen working on Windows on main.
  • pnpm --dir website build passes.

Open questions

none

Decisions

  • No ADR: the feature changes only the website.
  • Decided in the session (maintainer): check the gateway, the console screen stream and tunnels on Windows, document what works, and mark physical Android phones "not checked yet".
  • Decided in the session (maintainer): Windows setup lives on one new page under Worker, "Set up a Windows worker", linked from Requirements; other pages only fix their platform lines.
  • Decided in the session (maintainer): Windows commands are PowerShell.
  • Decided in the session (maintainer): before review, the implementing agent runs the Windows page's commands over ssh DesktopWindows, with its own SIMLOCK_HOME, the whole flow in one script per ssh session (a daemon started over SSH stops when the session ends), checking that no qemu-system-x86_64.exe runs before it boots one; the installer, PATH and script-policy steps rest on this session's facts (X13 to X33).
  • Decided in the session: the page sets the script policy with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned and names npm.cmd and simlock.cmd as the way round it, because Windows 11 refuses npm's .ps1 shims under its default policy (X27).
  • Decided in the session: the page adds the SDK's cmdline-tools\latest\bin, platform-tools and emulator folders to the user's Path, because neither Android Studio nor the command-line tools zip does, and the page's sdkmanager and emulator commands need them.
  • Decided in the session: the page installs the first system image with simlock component install android 35 after downloads.acceptAndroidLicenses, because doctor does not check for an image and a lease without one fails with RUNTIME_MISSING.
  • Decided in the session: JSON values on the Windows page are written for Windows PowerShell 5.1, the one Windows ships, with each " escaped as \"; the page says PowerShell 7.3 or later takes the macOS form (X28).
  • Decided in the session: the home page gets "Windows workers" in its feature list and a FAQ entry beside the Linux one, and keeps its Mac headline and animation, because the headline is the brand's story and the FAQ is where a Windows user looks.
  • Decided in the session: the pages describe the next release, because the site deploys at release; the Windows fixes after 0.8.0 (fix(android): empty the emulator log in place (#1662) #1669, fix(ports): the daemon launch works when SIMLOCK_HOME sits under a drive root #1672, fix(ports): npm runs from node_modules beside Node when the installer has no npm symlink #1673, fix(daemon): on Windows the data directory warning reads the folder's ACL #1674) ship with it.
  • Decided in the session: the service (Windows: simlock daemon install and uninstall run the daemon as a service #1691) and Windows CI (CI: run the tests on Windows #1693) features change these pages themselves when they ship, so this feature does not wait for them, and the pages keep "not on Windows yet" until then.

Behaviours

Every row's seam is the website page named, built with pnpm --dir website build; a row that states what Windows does is checked by running its commands on a Windows 11 machine (Facts X13 to X26 below were seen on DesktopWindows, Windows 11 23H2, at main 2df19f8).

Id Behaviour (invoker, action, what it sees) Seam Cases Task
B1 A reader opens Requirements and sees, for each row of the "At a glance" table, whether it runs on macOS, Linux and Windows, and a link to the Windows page introduction/requirements.mdx the seven rows of Examples; the Android SDK step keeps the Windows default path; "simlock doctor checks iOS only on macOS" stays #1701
B2 A Windows user follows "Set up a Windows worker" step by step, in PowerShell, from installing Node to a released Android lease new worker/windows.mdx, sidebar entry in website/astro.config.mjs under Worker Node 22.13+ from the official installer; Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, or else npm.cmd and simlock.cmd in place of npm and simlock (X27); npm i -g simlock (X25); Windows Hypervisor Platform on, virtualization on in the firmware, emulator -accel-check prints WHPX(...) is installed and usable. (X13); SDK from Android Studio at %LOCALAPPDATA%\Android\Sdk (X14), or the command-line tools unpacked to <sdk>\cmdline-tools\latest with ANDROID_HOME set for the user; the SDK's cmdline-tools\latest\bin, platform-tools and emulator folders added to the user's Path, then a new terminal; sdkmanager --install emulator platform-tools; a JDK with JAVA_HOME; simlock doctor prints {"findings":[],"sources":[]} (X15); simlock config set downloads.acceptAndroidLicenses true, simlock daemon stop, simlock component install android 35 (X18); simlock lease --platform android --detach, simlock adb -s <device.address> shell getprop ro.build.version.release, simlock release <lease-id> (X16, X17); a JSON value written with \" for Windows PowerShell 5.1 (X28); a missing tool: doctor's line, fix, simlock daemon stop, doctor again #1701
B3 The Windows page says what works on Windows, what does not and what is not checked, each in a table worker/windows.mdx works: Android emulator leases cold and warm (X16, X17), simlock adb, release, nuke, update (X25, X34), component install of an Android image (X18), the gateway and joining one (X19), the console's page (X20), screen streaming (X21), tunnels emulator adb, forward and reverse (X22, X23), agent-device through the worker's local profile (X24, X31), simlock setup's skill and simlock mcp (X30); does not: iOS simulators and iPhones (NO_DRIVER, X26), start at login (daemon install is a usage error, link to Run the daemon); not checked: physical Android phones, simlock cleanup, and setup --mcp registering Simlock with Claude Code or Codex on Windows #1701
B4 The Windows page says where Simlock keeps its files and how its daemon lives on Windows worker/windows.mdx data in %USERPROFILE%\.simlock, or $env:SIMLOCK_HOME; the CLI reaches the daemon over a named pipe, not daemon.sock (link to Programmatic client); the folder-access warning and its icacls command in the daemon log (X15); one user account per machine (link to the existing caution); the daemon keeps running when the terminal that started it closes (X5); started over SSH, it stops when the SSH session ends (maintainer's run, 2026-11-18); no start at login yet #1701
B5 A reader on any other page that names where Simlock runs reads the same answer as Requirements the pages in X1 to X4, X6 to X9, X32 each line in Existing code; the home page's feature list gains Windows workers, its FAQ gains "Can a Windows machine be a worker?" beside the Linux one, its gateway snippet and its "Add machines" step say "Mac, Linux or Windows"; the NO_DRIVER row of the error reference names iOS on Windows beside Linux; the headline, description and animation stay #1701
B6 A reader of Install and check your machine on Windows finds the Windows page from it getting-started/index.mdx a link next to "You need Node.js 22.13 or later, plus Xcode for iOS or the Android SDK for Android"; ~/.simlock gets its Windows path #1701

Stored state

none

Interfaces

none

Existing code

Commit 2df19f8.

Searches: rg -n -E "macOS or Linux|Mac or Linux|Mac and Linux|macOS and Linux|Macs and Linux|on macOS\b" website/src README.md (17 hits; the platform claims are below, the rest are about daemon install, which stays macOS and Linux only); rg -n -i linux website/src --glob '!content/docs/**' (13 hits in 4 files: the home page); rg -n win32 src --glob '!*.test.ts' (13 files: the Windows behaviour the page describes).

Id Code (path:line) Today With this feature Handled by
X1 website/src/content/docs/docs/introduction/requirements.mdx:14 to :17 CLI, Android emulators and the gateway "macOS or Linux" Windows added; a Windows column or wording per B1 B1
X2 website/src/content/docs/docs/introduction/index.mdx:30 "Install Simlock on the Mac or Linux machine" names Windows too B5
X3 website/src/content/docs/docs/introduction/how-it-works.mdx:13 "Android emulators, on macOS or Linux." macOS, Linux or Windows B5
X4 website/src/content/docs/docs/using-devices/choosing-a-device.mdx:51 "Android needs the Android SDK, on macOS or Linux." macOS, Linux or Windows B5
X5 src/ports/daemon-launcher.ts:127 to :135 the daemon is spawned detached with windowsHide, so it has no console window of its own to close and does not end with the terminal the Windows page states it (B4) B4
X6 website/src/content/docs/docs/gateway/index.mdx:10 "one Mac or Linux machine" one machine B5
X7 website/src/content/docs/docs/worker/running-the-daemon.mdx:138 the files table lists daemon.sock the row says that on Windows there is no file: the daemon listens on a named pipe B5
X8 README.md:10 "put more Macs and Linux machines behind a gateway" names Windows B5
X9 website/src/site/content.ts:84, :111, :152, :176 the feature list has Linux workers; the FAQ asks "Can a Linux machine be a worker?"; the gateway snippet says "on each worker, Mac or Linux"; the "Add machines" step says "point each Mac or Linux worker at it" Windows workers added; a Windows FAQ entry; "Mac, Linux or Windows" in both B5
X10 src/drivers/android/sdk-paths.ts:28 to :38 with no ANDROID_HOME or ANDROID_SDK_ROOT, Windows looks in %LOCALAPPDATA%\Android\Sdk the Windows page states it (B2) B2
X11 src/ports/paths.ts:79 on Windows the endpoint is a named pipe the Windows page links the pipe's description (B4) B4
X12 website/src/content/docs/docs/worker/running-the-daemon.mdx:92, website/src/content/docs/docs/reference/cli.mdx:412 daemon install and uninstall are not available on Windows unchanged; feature #1691 changes them when it ships B3

Seen on DesktopWindows (Windows 11 23H2, x64, emulator 37.2.13, platform-tools 37.0.1, cmdline-tools 23.0) at 2df19f8 on 2026-11-18, with the scripts of this session:

Id Code (path:line) Today With this feature Handled by
X13 run on DesktopWindows emulator -accel-check prints WHPX(10.0.22631) is installed and usable. the Windows page states it B2
X14 run on DesktopWindows with ANDROID_HOME and ANDROID_SDK_ROOT unset and the SDK at %LOCALAPPDATA%\Android\Sdk (a junction to D:\Android\Sdk), doctor prints no findings and status prints Host: Windows_NT 10.0.22631 x64; emulator 37.2.13, platform-tools 37.0.1, cmdline-tools 23.0 the Windows page states it B2
X15 run on DesktopWindows simlock doctor prints {"findings":[],"sources":[]}; the daemon log warns data directory D:\sv\spec1071 is accessible to other users (...); run icacls "D:\sv\spec1071" /inheritance:r /grant:r ... the Windows page states it B2, B4
X16 run on DesktopWindows a cold Android lease over HTTP is granted in 159 s; a fresh home's first one, seed included, in 246 s the Windows page states it B3
X17 run on DesktopWindows simlock lease --platform android --detach is granted in 4 s with a warm device ready, and simlock adb with shell getprop ro.build.version.release prints 15 (the run passed --lease, which a worker ignores; one emulator was running) the Windows page states it B2, B3
X18 run on DesktopWindows simlock component install android 34 (with downloads.acceptAndroidLicenses) installs google_apis/x86_64 through sdkmanager.bat, component list shows it installedBySimlock: true, and component remove android 34 --yes removes it the Windows page states it B3
X19 run on DesktopWindows simlock --gateway daemon start, token create, a worker joined with config set gateway, a lease through the gateway, --gateway status, --gateway release the Windows page states it B3
X20 run on DesktopWindows the worker's and the gateway's console answer GET / with 200 text/html the Windows page states it B3
X21 run on DesktopWindows GET /v1/leases/<id>/stream through the gateway answers 200 application/vnd.simlock.stream+h264, first bytes after 1.9 s, 434 KB in 25 s; worker list shows stream available -- tunnel available the Windows page states it B3
X22 run on DesktopWindows simlock tunnel ... emulator adb:15999 forward 19100:15100: adb: connected to 127.0.0.1:15999, adb -s 127.0.0.1:15999 shell getprop ro.product.model answers, the forward reads what toybox nc -l on the device sends the Windows page states it B3
X23 run on DesktopWindows simlock tunnel ... reverse 18081 prints reverse device:18081 -> localhost:18081; adb reverse --list on the device shows host-11 tcp:18081 tcp:47000, and a request from the device to 127.0.0.1:18081 and localhost:18081 gets the caller's answer the Windows page states it B3
X24 run on DesktopWindows a standalone worker's status --json shows {"name":"agent-device","state":"available"} the Windows page states it B3
X25 maintainer's run; #1673 (57f6382) npm i -g simlock and simlock update with the official Node installer the Windows page states it B2
X26 run on DesktopWindows simlock lease --platform ios --no-wait exits 12 with NO_DRIVER (No driver registered for platform: ios); simlock daemon install exits 2 with daemon install is supported on macOS and Linux only the Windows page states it B3
X27 run on DesktopWindows Windows PowerShell 5.1.22621; under -ExecutionPolicy Restricted, npm --version and agent-device --version fail with ...npm.ps1 cannot be loaded because running scripts is disabled on this system, and agent-device.cmd --version prints 0.21.36; npm's global folder holds <name>.ps1, <name>.cmd and <name> shims the Windows page states it B2
X28 run on DesktopWindows in Windows PowerShell 5.1, simlock config set gateway '{"url":...,"token":...}' fails with Invalid config value for "gateway": expected an object, so does a value from ConvertTo-Json; '{\"url\":...,\"token\":...}' is stored as an object; gateway.url and gateway.token set one at a time are each refused (expected a join token, since gateway.url is set) the Windows page states it B2
X29 run on DesktopWindows simlock daemon stop while a warm-pool emulator was booting failed after 300 s with SERVICE_FAILED (The running daemon did not stop within 300 s.); a start 35 s later worked not on the page; filed as bug #1700 —
X30 run on DesktopWindows simlock setup --project --tool claude-code --mcp --json writes .claude\skills\simlock\SKILL.md, reports mcp: skipped, claude not found and machine: android ok; simlock mcp over stdio answers initialize (simlock 1.0.0) and lists lease_simulator,list_devices,release_simulator,lease_status,run_on_device,rotate_device the Windows page states it B3
X31 run on DesktopWindows agent-device.cmd connect --remote-config D:\sv\spec1071\agent-device-profile.json, open --platform android (Leased device: Pixel 9, 35, virtual), snapshot (21 nodes), close the Windows page states it B3
X34 maintainer's run, brief for #1692 (2026-11-18) on main, doctor, daemon start and stop, cold and warm Android leases, simlock adb, release, nuke and simlock update work on Windows the Windows page states it B3
X32 website/src/content/docs/docs/reference/errors.mdx:53 NO_DRIVER: "iOS on Linux, or a platform whose tools are missing" "iOS on Linux or Windows" B5
X33 src/cli/commands/passthrough.ts:17 to :36 on a worker simlock adb ignores --lease and runs plain adb against Simlock's adb server; -s <device.address> names the device the Windows page uses -s (B2) B2

Tasks

Every Completion condition is delivered by #1701's Done when lines.

Open work in the same area:

Written by an agent.

Activity

  1. added
    feature:specSpec in progress, business and technical together.
    os:windowsRuns on, or affects, Windows hosts
    on Nov 18, 2026
  2. V3RON commented on Nov 18, 2026

    @V3RON
    ContributorAuthor

    Design posted: business sections, Decisions, Behaviours B1–B6 (one task), Existing code X1–X26 with the facts seen on a Windows 11 machine (gateway, stream, all three tunnels, image install, agent-device, iOS refusal).

    Written by an agent.

  3. V3RON commented on Nov 18, 2026

    @V3RON
    ContributorAuthor

    Spec updated: approved by the maintainer; task #1701 written (B1–B6), Task cells and the Tasks section filled, open work in the same area listed.

    Written by an agent.

  4. added
    feature:plannedSplit into tasks. Never picked up itself.
    and removed
    feature:specSpec in progress, business and technical together.
    on Nov 18, 2026
  5. V3RON commented on Nov 18, 2026

    @V3RON
    ContributorAuthor

    Delivery run

    Merged: #1711 (#1701)
    Parked: none
    Waiting: none
    Decided: #1701 — the home FAQ with a separate Windows entry has 7 entries in a 3-column grid (half-empty row) → one entry, "Can a Windows or Linux machine be a worker?", 6 entries (pending the maintainer)

    Written by an agent.

  6. github-actions commented on Nov 18, 2026

    @github-actions
    Contributor

    Closing: all 1 sub-issues are closed. The PR that closed the last one walks the completion conditions (delivery rule 9); reopen this if one does not hold on main. Flip its ADRs to Accepted if delivery has not.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:plannedSplit into tasks. Never picked up itself.os:windowsRuns on, or affects, Windows hosts

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions