Repository navigation
Description
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"]
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.sockfile on macOS and Linux, e.g.\\.\pipe\simlock-1a2b3c4d5e6f7a8b.
Non-goals
- Starting the daemon at login on Windows: Windows: simlock daemon install and uninstall run the daemon as a service #1069 (feature Windows: simlock daemon install and uninstall run the daemon as a service #1691) adds it and updates these pages.
- A Windows CI job: CI: run the tests on Windows #1070 (feature CI: run the tests on Windows #1693).
- Checking physical Android phones on Windows. The page says they are not checked yet.
- cmd.exe commands. Windows commands are PowerShell only.
- Changing the home page's headline or animation, which tell the Mac story.
- Any code change. A bug found while checking is filed as
bug:new, not fixed here (Windows: daemon stop times out after 300 s while the warm pool remakes an Android seed (EBUSY on cache.img) #1700).
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 adbcommand 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 buildpasses.
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 ownSIMLOCK_HOME, the whole flow in one script per ssh session (a daemon started over SSH stops when the session ends), checking that noqemu-system-x86_64.exeruns 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 RemoteSignedand namesnpm.cmdandsimlock.cmdas the way round it, because Windows 11 refuses npm's.ps1shims under its default policy (X27). - Decided in the session: the page adds the SDK's
cmdline-tools\latest\bin,platform-toolsandemulatorfolders to the user'sPath, because neither Android Studio nor the command-line tools zip does, and the page'ssdkmanagerandemulatorcommands need them. - Decided in the session: the page installs the first system image with
simlock component install android 35afterdownloads.acceptAndroidLicenses, because doctor does not check for an image and a lease without one fails withRUNTIME_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
- Docs: a Windows worker page, and every platform line names Windows #1701 Docs: a Windows worker page, and every platform line names Windows — a Windows user sets up an Android worker from the website alone, and every page agrees on where Simlock runs. Risk: a step on the page fails as written on a fresh Windows 11.
Every Completion condition is delivered by #1701's Done when lines.
Open work in the same area:
- A worker refuses the iOS modes it does not serve (ios.modes, MODE_UNAVAILABLE) #1651 (PR feat(leasing): a worker refuses the iOS modes it does not serve (ios.modes, MODE_UNAVAILABLE) #1697) adds a row to
reference/errors.mdxnearNO_DRIVERand editsusing-devices/choosing-a-device.mdxfurther down. No Depends on: different lines; whichever merges second rebases. - PR feat(android): add an AgentDeviceCloud backend #1498 adds a Worker sidebar entry in
website/astro.config.mjs. No Depends on: a different line of the same list. - Windows: simlock daemon install and uninstall run the daemon as a service #1691 (start at login on Windows; task Windows: simlock daemon install runs the daemon from a logon task with a Simlock supervisor #1698, ready) and CI: run the tests on Windows #1693 (Windows CI) change these pages when they ship. No Depends on in either direction: Windows: simlock daemon install runs the daemon from a logon task with a Simlock supervisor #1698 adds the Windows page's start-at-login lines if Docs: a Windows worker page, and every platform line names Windows #1701 merged first, and Docs: a Windows worker page, and every platform line names Windows #1701's Done when lists start at login as working if Windows: simlock daemon install runs the daemon from a logon task with a Simlock supervisor #1698 merged first.
- On Windows, simlock status lists iOS capacity and counts it in the global limit #1689 (status lists iOS capacity on Windows): the page shows no
simlock statusoutput with iOS lines, so it stays true either way.
Written by an agent.
Activity
V3RON commentedon Nov 18, 2026
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.
V3RON commentedon Nov 18, 2026
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.
docs(website): a Windows worker page, and every platform line names W…
V3RON commentedon Nov 18, 2026
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.
github-actions commentedon Nov 18, 2026
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.