Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: add Windows testing guide and the npm agents investigation

leepokaib3e8ebf340a1
diff --git a/docs/README.md b/docs/README.md
index b6a5258e..5055cc7e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ Source review, a passing build, local integration tests and production acceptanc
| Test a phone over Cloudflare instead of LAN | [Cloudflare testing](guides/cloudflare-testing.md) |
| Configure dev/main or deploy the services | [Environments and deployment](guides/environments-and-deployment.md) |
| Run the host on a Linux server or cloud VM | [Linux servers](guides/linux-servers.md) |
+| Reproduce or check something on Windows (UTM VM) | [Windows testing](guides/windows-testing.md) |
| Set up accounts, approvals or desktop SSH | [Accounts and SSH](guides/accounts-and-ssh.md) |
| Change transport or cryptography | [Remote protocol](reference/remote-relay.md) and [shared vectors](reference/fixtures/README.md) |
| Change what the host and clients exchange | [Client and host compatibility](reference/compatibility.md) |
diff --git a/docs/archive/README.md b/docs/archive/README.md
index 989f21bd..90323e2a 100644
--- a/docs/archive/README.md
+++ b/docs/archive/README.md
@@ -12,3 +12,4 @@ These documents retain decisions and observations from before the current refact
Do not interpret old “not implemented” statements, delegation assignments, version numbers or test reports as the state of the current checkout. Reassess an audit finding against source before turning it into work.
- [Widget verification record, 2026-09-26](mobile-widgets-verification-2026-09-26.md): historical observations and remaining system integration checks.
+- [npm agents failing to start on Windows, 2026-10-14](windows-npm-agents-2026-10-14.md): PostHog signal, VM reproduction, root cause and fix (2.16.1).
diff --git a/docs/archive/windows-npm-agents-2026-10-14.md b/docs/archive/windows-npm-agents-2026-10-14.md
new file mode 100644
index 00000000..1bdb184a
--- /dev/null
+++ b/docs/archive/windows-npm-agents-2026-10-14.md
@@ -0,0 +1,76 @@
+# npm agents failing to start on Windows — 2026-10-14
+
+> Historical record of one investigation, not a current test result. How to test on Windows:
+> [Windows testing](../guides/windows-testing.md).
+
+## Signal
+
+PostHog `turn_finished`, 14 days to 2026-10-14, production builds, internal accounts and automated
+test hosts excluded:
+
+| Agent on Windows | Start failures | Successful turns |
+|---|---|---|
+| Claude (2.14.0–2.15.2) | 19, from 12 users | 2, from one user |
+| Claude, 2.15.2 only | 5, from 3 users | 0 |
+| Codex | 11 | 4 |
+| Antigravity, 2.15.2 | 5 | 0 |
+
+Agents shipped as binaries (OpenCode, Grok) worked on Windows in the same period. The failure kind
+wasn't recorded yet (`turn_finished.error` came later), so the cause had to be reproduced.
+
+## Reproduction
+
+VM "Codync Windows", Codync v2.16.0 from the GitHub release, analytics turned off on the host.
+
+1. **No Node.js**: a Claude bot fails with `Couldn't start the agent: Claude Agent has no build for
+ this computer (needs Node.js)`. The registry's `[email protected]` and `[email protected]` are
+ npx-only.
+2. **Claude Code installed** with the host's own Windows command
+ (`irm https://claude.ai/install.ps1 | iex`): the agent list reports `installed: true,
+ available: false`, the picker still says "(not installed)" with the hint "Install Claude Code
+ and run `claude auth login`", and sending gives the same "needs Node.js" error.
+3. **Node.js 24 installed** (`winget`): `Couldn't start the agent: couldn't download Claude Agent
+ with npm: npm notice`. Running the host's prefetch by hand from `%USERPROFILE%\.codync`,
+ `npm exec --yes --package @agentclientprotocol/[email protected] -c true`, prints
+ `'true' is not recognized as an internal or external command, operable program or batch file.`
+ and exits 1. The package itself had downloaded; the host then deletes the half-prepared cache
+ folder and fails, so every message repeats the download and the failure.
+4. **Same prefetch with `-c "exit 0"`**: exits 0 and leaves `package.json` in the cache. The Claude
+ bot then answers `Authentication required` and Codex `Codex needs you to sign in…`: the expected
+ sign-in states, so the rest of the launch works.
+
+## Root cause
+
+`prepare_npx` (`host/src/agent/registry.rs`) downloads an npm adapter with
+`npm exec --yes --package <pkg> -c true`. npm runs `-c` through `cmd.exe` on Windows, which has no
+`true` command, so the download always "failed" there. The line dates from f5fa9eae (v2.2.2), so
+every Windows release had it. The visible error was npm's update notice because the host reported
+the last line of stderr.
+
+## Fix
+
+7747a378 (2.16.1): the prefetch runs `-c "exit 0"`, which both `sh` and `cmd.exe` understand, and a
+failed download reports the last stderr line that isn't an `npm notice`.
+
+## Verification
+
+- Done: a unit test for the error line; on the Mac, `npm exec … -c "exit 0"` exits 0 (and
+ `"exit 3"` exits 3); a debug host with an empty npm cache downloaded the Claude adapter through the
+ new prefetch, started it, and the bot replied.
+- Done in the VM by hand: steps 3 and 4 above, running the exact npm command.
+- Not done: the 2.16.1 host itself on Windows (no local Windows build; see
+ [limits](../guides/windows-testing.md#limits)). After 2.16.1 ships, repeat step 4 with a Claude
+ bot in the VM, and check that Windows `turn_finished` with `stop_reason = start_failed` drops in
+ PostHog.
+
+## Seen, not fixed
+
+- Without Node.js, an npx-only agent's install hint still names the harness setup (Claude Code),
+ which is already done; it should say to install Node.js. `list()` in
+ `host/src/agent/backends.rs`.
+- Every new bot on Windows posts `Memory is unavailable; … installing Engram: Access is denied.
+ (os error 5)`.
+
+VM state left behind: Codync 2.16.0 installed as the service (analytics off), Claude Code 2.1.299,
+Node.js 24.20.0 (arm64), test bots `ClaudeTest` and `CodexTest`, and the claude-acp and codex-acp
+npx caches.
diff --git a/docs/guides/windows-testing.md b/docs/guides/windows-testing.md
new file mode 100644
index 00000000..326a6277
--- /dev/null
+++ b/docs/guides/windows-testing.md
@@ -0,0 +1,59 @@
+# Windows testing
+
+Codync ships an x64 Windows app (Electron + the bundled `codync-host.exe`). Real Windows behavior is
+checked in a UTM virtual machine on the Mac. Everyday end-to-end checks stay on the Mac; use the VM
+when a change or a bug depends on Windows itself (paths, `cmd.exe`, `.cmd` shims, the service).
+
+## The VM
+
+- **UTM "Codync Windows"**: Windows 11 ARM64 (Codync's x64 build runs through Prism emulation),
+ 8 GB / 4 cores / 64 GB NVMe, account `codync` / `codync`, signs in automatically.
+- **Start / stop** from the Mac, never through UTM's window:
+ `osascript -e 'tell application "UTM" to start virtual machine named "Codync Windows"'`
+ (`stop … by force` only when a normal stop hangs; `query ip of …` works). `utmctl` fails with
+ OSStatus -10004. Pressing UTM's Run button through accessibility crashed UTM once; if UTM is in a
+ bad state, quit it and reopen it in the background with `open -g -a UTM`.
+- **Shell**: `ssh codync-win` (PowerShell). The `~/.ssh/config` alias points at `192.168.64.4` with
+ the key `~/.ssh/codync_windows_vm`.
+- **GUI apps** must start in the signed-in session (session 2):
+ `schtasks /create /tn X /tr <exe> /sc once /st 23:59 /it /f; schtasks /run /tn X`.
+- **Screen** without touching the Mac's UI: QEMU VNC on `127.0.0.1:5905`, e.g.
+ `uvx --from vncdotool vncdo --force-caps -s 127.0.0.1::5905 capture x.png`. Input lags a few
+ seconds; `--force-caps` is needed for symbols.
+- The Mac sleeping pauses the VM: wrap long installs in `caffeinate -i`.
+- Rebuilding the VM: the unattended install assets live in `~/VMs/codync-windows/` (about 20
+ minutes). NVMe must be the first drive and both ISOs detached afterwards, or Windows reinstalls on
+ every boot.
+
+## Testing a build
+
+1. Install the release under test (`codync-windows-x64.exe` from the GitHub release). The first
+ launch asks Defender Firewall about `codync-host`; the host then starts at sign-in.
+2. **Turn analytics off on the test host before anything else**, so the VM never counts as a user:
+ `setAnalytics {"enabled": false}`.
+3. Drive the host over SSH instead of the GUI where possible. The API is loopback-only, which SSH
+ satisfies:
+
+ ```powershell
+ $t = Get-Content "$env:USERPROFILE\.codync\token"
+ Invoke-RestMethod -Method Post -Uri http://127.0.0.1:19222/api/backends `
+ -Headers @{ Authorization = "Bearer $t" } -ContentType application/json -Body '{}'
+ ```
+
+ `createBot`, `send` and `history` cover most agent checks; a failed start shows up as an error
+ notice in `history`. Host logs are under `%USERPROFILE%\.codync`.
+4. Agents: install each harness with the command its setup hint gives (Claude Code:
+ `irm https://claude.ai/install.ps1 | iex`). Adapters that come from npm (Claude, Codex, Gemini,
+ Qwen, …) also need Node.js (`winget install OpenJS.NodeJS`); agents shipped as binaries
+ (OpenCode, Grok) don't.
+
+## Limits
+
+- An unreleased host can't be built on the Mac for Windows (its C dependencies need a MinGW
+ toolchain that isn't installed). CI builds Windows only for pull requests and tags
+ (`.github/workflows/host.yml`), so a fix is usually reproduced by hand in the VM first (running
+ the exact command the host would) and checked on Windows again with the next release.
+- `cfg(windows)` code can still be compile-checked on the Mac by copying it into a scratch crate and
+ running clippy with the pinned toolchain's `--target x86_64-pc-windows-gnu`.
+
+Investigations done this way: [npm agents failing to start on Windows, 2026-10-14](../archive/windows-npm-agents-2026-10-14.md).