Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(cli): signed hosted installers, clean-container tests, doctor docs and routes for one-command client setup

nirholasfa56d5fc25f9
diff --git a/STRUCTURE.md b/STRUCTURE.md
index d2d31a14c..dc148a0d6 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -239,7 +239,7 @@ bottom.
| On-chain agent invocation | [contracts/agent-invocation/](contracts/agent-invocation) | In-repo | Anchor program: verifiable agent-to-agent skill invocation events. SDK: [agent-protocol-sdk/](agent-protocol-sdk) |
| Escrowed knocks (pay-per-reply) | [contracts/knock-escrow/](contracts/knock-escrow) | In-repo | Anchor program making a knock's payment conditional instead of final: `knock` parks the price in a vault owned by the knock's own PDA, and only three things can happen to it. `answer` pays the owner minus a fee capped at 10% in the program itself, `refuse` refunds the sender in full and takes no fee, and `reclaim` refunds the sender once the reply window closes and can be called by anyone. Each `KnockRecord` snapshots the fee that was in force when it was made, so an authority cannot reprice money already in escrow, and it stores only the SHA-256 of the message and the reply, never their text. The trust-me version of this settles straight to the owner at [api/knock/](api/knock) (row above); this is the version that works between strangers. Both sides are reachable from a browser: senders escrow and crank their own refund from the door page, owners open their on-chain door, answer for payment or refuse for a refund from [/knock](pages/knock.html), all signed by their own wallet ([src/knock/escrow-checkout.js](src/knock/escrow-checkout.js)). Docs: [contracts/knock-escrow/README.md](contracts/knock-escrow/README.md), [docs/knock.md](docs/knock.md). Tests: [tests/knock-escrow-program.test.js](tests/knock-escrow-program.test.js), [tests/knock-escrow-pda.test.js](tests/knock-escrow-pda.test.js), [tests/api-knock-escrowed.test.js](tests/api-knock-escrowed.test.js), [tests/api-knock-escrow-sync.test.js](tests/api-knock-escrow-sync.test.js) |
| Cross-chain SDKs | [sdk/](sdk), [solana-agent-sdk/](solana-agent-sdk), [agent-payments-sdk/](agent-payments-sdk), [agent-protocol-sdk/](agent-protocol-sdk) | Published | Cross-chain agent SDKs |
-| MCP integration | [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge), [packages/*-mcp/](packages) | 43 npm servers + 7 hosted remote (50 total, incl. the free `/api/mcp-studio` 3D Studio, whose ChatGPT plugin surface [api/mcp-chatgpt.js](api/mcp-chatgpt.js) `→ /api/mcp-chatgpt` serves the eight 3D tools and the model viewer without the persona tools or any `frameDomains`, and [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` serves every studio tool with no widget templates plus, for a caller signed in with OAuth 2.1 or a connector key, the account's agent tools from the core server through [api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), never a value-moving one ([tests/mcp-grok-accounts.test.js](tests/mcp-grok-accounts.test.js)); all three doors share [api/_mcp-studio/handler.js](api/_mcp-studio/handler.js), and `SURFACES` in [api/_mcp-studio/dispatch.js](api/_mcp-studio/dispatch.js) defines what each advertises), all in the [MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas). Canonical metadata: [prompts/store-submissions/_generated/mcp-listing-source.json](prompts/store-submissions/_generated/mcp-listing-source.json), generated from the manifests by [scripts/build-mcp-listing-source.mjs](scripts/build-mcp-listing-source.mjs) (`npm run audit:mcp-listing` fails when it drifts) | Model Context Protocol surface, full server list in [docs/mcp.md](docs/mcp.md). One-click client setup: [pages/connect.html](pages/connect.html) `→ /connect` (Claude, Cursor and VS Code install links plus ChatGPT, Claude Code and generic steps, built live from [public/.well-known/mcp.json](public/.well-known/mcp.json) with tool counts from the catalog; config names match the CLI's `slugForPath`). CLI: [packages/three-ws-cli/](packages/three-ws-cli) (`npx three-ws setup`), docs [docs/cli.md](docs/cli.md) `→ /docs/cli`. Searchable index of every tool: [pages/mcp-tools.html](pages/mcp-tools.html) `→ /mcp-tools`, rendered from the generated [public/mcp-catalog.json](public/mcp-catalog.json) ([scripts/build-mcp-catalog.mjs](scripts/build-mcp-catalog.mjs), `npm run build:mcp-catalog`, staleness gated by `npm run audit:mcp-catalog`). Tool safety annotations are verified against each handler by [scripts/audit-mcp-safety.mjs](scripts/audit-mcp-safety.mjs) (`npm run audit:mcp-safety`, rules in [scripts/lib/mcp-safety-check.mjs](scripts/lib/mcp-safety-check.mjs), guarded-file list shared with the golden snapshot via [scripts/lib/mcp-tool-sources.mjs](scripts/lib/mcp-tool-sources.mjs)); docs [docs/mcp-safety.md](docs/mcp-safety.md) `→ /docs/mcp-safety`. Trust policy: [api/mcp-policy.js](api/mcp-policy.js) `-> GET /api/mcp-policy` turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on `/mcp-tools`. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): [scripts/audit-mcp-reviewer-path.mjs](scripts/audit-mcp-reviewer-path.mjs), `npm run audit:mcp-reviewer`. Tests: [tests/mcp-safety-audit.test.js](tests/mcp-safety-audit.test.js), [tests/mcp-catalog.test.js](tests/mcp-catalog.test.js), [tests/api/mcp-policy.test.js](tests/api/mcp-policy.test.js) |
+| MCP integration | [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge), [packages/*-mcp/](packages) | 43 npm servers + 7 hosted remote (50 total, incl. the free `/api/mcp-studio` 3D Studio, whose ChatGPT plugin surface [api/mcp-chatgpt.js](api/mcp-chatgpt.js) `→ /api/mcp-chatgpt` serves the eight 3D tools and the model viewer without the persona tools or any `frameDomains`, and [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` serves every studio tool with no widget templates plus, for a caller signed in with OAuth 2.1 or a connector key, the account's agent tools from the core server through [api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), never a value-moving one ([tests/mcp-grok-accounts.test.js](tests/mcp-grok-accounts.test.js)); all three doors share [api/_mcp-studio/handler.js](api/_mcp-studio/handler.js), and `SURFACES` in [api/_mcp-studio/dispatch.js](api/_mcp-studio/dispatch.js) defines what each advertises), all in the [MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas). Canonical metadata: [prompts/store-submissions/_generated/mcp-listing-source.json](prompts/store-submissions/_generated/mcp-listing-source.json), generated from the manifests by [scripts/build-mcp-listing-source.mjs](scripts/build-mcp-listing-source.mjs) (`npm run audit:mcp-listing` fails when it drifts) | Model Context Protocol surface, full server list in [docs/mcp.md](docs/mcp.md). One-click client setup: [pages/connect.html](pages/connect.html) `→ /connect` (Claude, Cursor and VS Code install links plus ChatGPT, Claude Code and generic steps, built live from [public/.well-known/mcp.json](public/.well-known/mcp.json) with tool counts from the catalog; config names match the CLI's `slugForPath`). CLI: [packages/three-ws-cli/](packages/three-ws-cli) (`npx three-ws setup`), docs [docs/cli.md](docs/cli.md) `→ /docs/cli`. One-command setup per client (`npx three-ws --claude`), `doctor`, `agent status` and `team` live in [packages/three-ws-cli/src/commands/](packages/three-ws-cli/src/commands); the hosted installers [public/cli/](public/cli) (`/cli/install`, `/cli/claude`, each with a `.sha256` and an ed25519 `.sig`, public key `signing-key.pem`) are signed by [scripts/sign-cli-scripts.mjs](scripts/sign-cli-scripts.mjs) (`npm run sign:cli`, verified by `npm run check:cli-scripts` in the gate); the clean-container check is [packages/three-ws-cli/tests/container/run.sh](packages/three-ws-cli/tests/container/run.sh). Searchable index of every tool: [pages/mcp-tools.html](pages/mcp-tools.html) `→ /mcp-tools`, rendered from the generated [public/mcp-catalog.json](public/mcp-catalog.json) ([scripts/build-mcp-catalog.mjs](scripts/build-mcp-catalog.mjs), `npm run build:mcp-catalog`, staleness gated by `npm run audit:mcp-catalog`). Tool safety annotations are verified against each handler by [scripts/audit-mcp-safety.mjs](scripts/audit-mcp-safety.mjs) (`npm run audit:mcp-safety`, rules in [scripts/lib/mcp-safety-check.mjs](scripts/lib/mcp-safety-check.mjs), guarded-file list shared with the golden snapshot via [scripts/lib/mcp-tool-sources.mjs](scripts/lib/mcp-tool-sources.mjs)); docs [docs/mcp-safety.md](docs/mcp-safety.md) `→ /docs/mcp-safety`. Trust policy: [api/mcp-policy.js](api/mcp-policy.js) `-> GET /api/mcp-policy` turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on `/mcp-tools`. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): [scripts/audit-mcp-reviewer-path.mjs](scripts/audit-mcp-reviewer-path.mjs), `npm run audit:mcp-reviewer`. Tests: [tests/mcp-safety-audit.test.js](tests/mcp-safety-audit.test.js), [tests/mcp-catalog.test.js](tests/mcp-catalog.test.js), [tests/api/mcp-policy.test.js](tests/api/mcp-policy.test.js) |
| Grok Bot integration | Door [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` on the shared studio handler [api/_mcp-studio/](api/_mcp-studio), account tools [api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), install tokens [api/mcp-studio/install.js](api/mcp-studio/install.js), landing page [pages/grok.html](pages/grok.html) `→ /grok`, skill file [public/grok-skill.md](public/grok-skill.md) (template [data/grok-skill-md.template.md](data/grok-skill-md.template.md)), `/connect` Grok Bot tab [pages/connect.html](pages/connect.html), connector probe [scripts/mcp-client-probe.mjs](scripts/mcp-client-probe.mjs) (`npm run probe:mcp-clients`) | Free remote MCP server for Grok Bot, Grok connectors and the xAI API: no call hangs, quota per MCP session or install token, OAuth 2.1 or a connector API key adds agent tools and never a spend tool. Connector reference: [docs/grok-bot.md](docs/grok-bot.md) `→ /docs/grok-bot`; product tour [docs/grok.md](docs/grok.md) |
| X creation claim | Page [pages/x-claim.html](pages/x-claim.html) `→ /x/claim` ([src/x-claim.js](src/x-claim.js)), API [api/x/claim.js](api/x/claim.js), logic [api/_lib/x-creation-claim.js](api/_lib/x-creation-claim.js), ledger migration [api/_lib/migrations/20261009213000_x_creation_claims.sql](api/_lib/migrations/20261009213000_x_creation_claims.sql) | Models the @-mention bot made for an X author move from the bot account into their library when they link the same X id (on link, on the page, or at creation time). Doc: [docs/x-mention-bot.md](docs/x-mention-bot.md). Tests: [tests/x-creation-claim.test.js](tests/x-creation-claim.test.js) |
| Awesome 3D Agents (curated list) | Source [data/awesome.json](data/awesome.json), generator [scripts/build-awesome.mjs](scripts/build-awesome.mjs) (`npm run build:awesome`, drift-gated by `npm run check:awesome`, publishable mirror via `npm run awesome:standalone`), outputs [awesome/README.md](awesome/README.md) + [public/awesome.json](public/awesome.json), page [pages/awesome.html](pages/awesome.html) `-> /awesome`, link checker [scripts/check-awesome-links.mjs](scripts/check-awesome-links.mjs) (`npm run awesome:links`) | Live | An awesome-list of everything needed to give an AI agent a body: text-to-3D, capture and splatting, avatars, rigging, motion, lipsync and voice, web renderers, asset pipelines, physics and networking, agent frameworks, datasets, free assets, learning. One JSON source produces both the GitHub-facing list and the searchable page, so they cannot disagree. Every url is fetched and classified (ok / moved / bot-filtered / broken) before it ships; the checker stays out of the deploy path so a third-party outage cannot redden someone else's build. The README is written to pass `npx awesome-lint`: badge on the heading line, no License section, no Contributing entry in the contents, and every description capitalised and ended with a period, all enforced by the generator and by [tests/awesome-list.test.js](tests/awesome-list.test.js). Its last two lint rules read GitHub repository topics, which a list inside a product repo cannot satisfy, so `--standalone` emits a ready-to-publish mirror repo (readme, contributing, code of conduct, license) outside this checkout. Contributing: [awesome/CONTRIBUTING.md](awesome/CONTRIBUTING.md) |
diff --git a/data/changelog.json b/data/changelog.json
index 6bcdb84e9..f5f9ae729 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -29432,6 +29432,16 @@
"fix"
],
"link": "/gestures"
+ },
+ {
+ "date": "2026-10-10",
+ "title": "Set up your AI client with one command, and check it with doctor",
+ "summary": "Run npx three-ws --claude (or --cursor, --codex, --vscode, --windsurf) and the CLI signs you in, connects three.ws and verifies it, with no prompts. Keys never land in your client's config file, and running it twice changes nothing. New installers at three.ws/cli/install and three.ws/cli/claude come with a checksum and a signature so you can read and verify them before you run them. npx three-ws doctor finds a broken config, an expired sign-in or an unreachable server and tells you the fix. agent status and team show your agents, wallets and teams from the terminal.",
+ "tags": [
+ "feature",
+ "improvement"
+ ],
+ "link": "/docs/cli"
}
]
}
diff --git a/docs/cli.md b/docs/cli.md
index 4c478f1ae..322482692 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -131,6 +131,10 @@ The selection is enforced whichever way you signed in. With a browser sign-in, s
| Command | What it does |
|---|---|
| `setup` | Sign in, write servers into clients, verify with `tools/list` |
+| `--claude` / `--cursor` / `--codex` / `--vscode` / `--windsurf` | Non-interactive setup for one client; keeps secrets out of its config |
+| `doctor` | Diagnose Node, credentials, auth, client configs and server reachability |
+| `agent status` | Your agents with wallet address and balances |
+| `team` / `team status <id>` | Your teams and one team's detail |
| `login` / `logout` | Sign in or switch accounts; `logout` also revokes the OAuth refresh token |
| `status` / `whoami` | Account, plan, wallet balance, token expiry and every configured client |
| `create [name]` | Create an agent with its own Solana wallet and public page |
@@ -145,6 +149,88 @@ The selection is enforced whichever way you signed in. With a browser sign-in, s
| `usage` | Credits, burn rate, days left and recent top-ups |
| `ask "<prompt>"` | One completion through the active provider |
+## One command per client
+
+Name a client and the CLI does the whole setup without prompts: sign in, write the servers, verify them with a live `tools/list`.
+
+```bash
+npx three-ws --claude # Claude Code, plus the three.ws skill
+npx three-ws --cursor
+npx three-ws --codex
+npx three-ws --vscode
+npx three-ws --windsurf
+npx three-ws --gemini
+```
+
+`--bob` and `--hermes` work the same way. Combine flags to set up several clients at once (`npx three-ws --cursor --vscode`), and add `--project` for config in the current directory, `--device` over SSH, or `--key sk_live_...` for CI.
+
+These flags write a launcher entry (`three-ws proxy <url>`) instead of a token. The OAuth token or API key stays in `~/.config/three-ws/credentials.json` (mode 600) and never appears in a client config file, so you can commit a project config safely. Running a command twice changes nothing the second time.
+
+With `--claude` the CLI also installs the three.ws skill at `~/.claude/skills/three-ws/SKILL.md`, so you can start Claude Code with:
+
+```bash
+claude "launch my agent"
+```
+
+### Hosted installers
+
+Two shell scripts do the same from a bare machine. `install` checks your OS and Node version, runs the CLI, and prints next steps. `claude` wires Claude Code and offers to start `claude "launch my agent"`.
+
+```bash
+curl -fsSL https://three.ws/cli/install | sh
+curl -fsSL https://three.ws/cli/claude | sh
+```
+
+Pass options after `--`: `curl -fsSL https://three.ws/cli/install | sh -s -- --cursor`. Both scripts need Linux or macOS (Windows: use WSL) and Node.js 20.12 or newer. They never use `sudo`, never edit your shell profile, never install Node for you, and never write a credential to disk themselves. Environment variables: `THREE_WS_VERSION` pins a CLI version and `THREE_WS_ORIGIN` points at another deployment.
+
+### Verify before you run
+
+Piping a script into a shell trusts whatever the server sends, so every script is published with a SHA-256 checksum and an ed25519 signature. Download, read, verify, then run:
+
+```bash
+mkdir three-ws-install && cd three-ws-install
+curl -fsSLO https://three.ws/cli/install.sh
+curl -fsSLO https://three.ws/cli/install.sh.sha256
+curl -fsSLO https://three.ws/cli/install.sh.sig
+curl -fsSLO https://three.ws/cli/signing-key.pem
+
+less install.sh # read it
+sha256sum -c install.sh.sha256 # checksum (macOS: shasum -a 256 -c install.sh.sha256)
+
+# signature (OpenSSL 3)
+openssl pkeyutl -verify -pubin -inkey signing-key.pem -rawin -in install.sh -sigfile install.sh.sig
+
+sh install.sh
+```
+
+Without OpenSSL 3, Node checks it:
+
+```bash
+node -e "const c=require('crypto'),f=require('fs');console.log(c.verify(null,f.readFileSync('install.sh'),c.createPublicKey(f.readFileSync('signing-key.pem')),f.readFileSync('install.sh.sig')))"
+```
+
+It prints `true` for an untouched script. The signing key's fingerprint (SHA-256 of its DER public key) is `662f5682e54fec906904b39937f8858a6c269b671fc335bff4b91c6a66a3f27d`, and the same key is committed in the repository at `public/cli/signing-key.pem`. Compare the two sources before trusting a key you downloaded from the same server as the script. The same steps work for `claude.sh`.
+
+Each script defines functions and calls `main` on its last line, so a download cut short runs nothing.
+
+## Check your setup
+
+```bash
+npx three-ws doctor
+```
+
+`doctor` finds a bad config before you do. It checks the Node version, the credential file and its permissions, that three.ws is reachable, that your sign-in is still valid (expired or revoked), each client's config (unparseable file, missing three.ws entry, a secret stored in plain text, a launcher missing from `PATH`), and a live `tools/list` for every configured server. Every problem comes with the command that fixes it. It exits 1 when anything fails, and `--json` prints the findings for scripts.
+
+## Agents and teams
+
+```bash
+npx three-ws agent status # each agent, its wallet address and SOL / USDC balance
+npx three-ws team # your teams
+npx three-ws team status <id-or-name>
+```
+
+Both are read-only.
+
Global flags: `--json` for machine-readable output, `--origin <url>` (or `THREE_WS_ORIGIN`) to talk to another deployment, `--no-color`.
## Troubleshooting
diff --git a/package.json b/package.json
index 807dc8299..d0e11c6a7 100644
--- a/package.json
+++ b/package.json
@@ -252,7 +252,7 @@
"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs",
"audit:handlers": "node scripts/audit-empty-handlers.mjs",
"audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",
- "gate": "npm run check:conflicts && npm run check:claude && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run check:mcp-catalog && npm run audit:mcp-listing && npm run audit:mcp-surfaces && npm run check:pay-skills && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run check:prompt-library && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:ios-app && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:skills-pack && npm run check:skill-repos && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:cli-scripts && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run check:mcp-catalog && npm run audit:mcp-listing && npm run audit:mcp-surfaces && npm run check:pay-skills && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run check:prompt-library && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:ios-app && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:skills-pack && npm run check:skill-repos && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
"test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js",
"audit:mcp-golden": "node scripts/audit-mcp-golden.mjs",
"audit:mcp-safety": "node scripts/audit-mcp-safety.mjs",
@@ -420,6 +420,8 @@
"check:tutorials": "node scripts/sync-tutorial-pages.mjs",
"tutorials:sync": "node scripts/sync-tutorial-pages.mjs --write",
"check:claude": "node scripts/check-claude-md.mjs",
+ "sign:cli": "node scripts/sign-cli-scripts.mjs",
+ "check:cli-scripts": "node scripts/sign-cli-scripts.mjs --check",
"verify:erc8004-validation": "node scripts/erc8004/verify-validation-registry.mjs",
"check:rules": "node scripts/check-rules.mjs",
"check:fetch-timeouts": "node scripts/check-fetch-timeouts.mjs",
diff --git a/packages/three-ws-cli/README.md b/packages/three-ws-cli/README.md
index 8b3ddd35f..1f6a5ee72 100644
--- a/packages/three-ws-cli/README.md
+++ b/packages/three-ws-cli/README.md
@@ -14,6 +14,30 @@ The three.ws MCP servers give your assistant 3D generation (text to 3D, image to
Using one client that supports remote connectors? [three.ws/connect](https://three.ws/connect) adds three.ws to Claude, Cursor or VS Code in one click, with no terminal.
+## One command per client
+
+```bash
+npx three-ws --claude # also --cursor --codex --vscode --windsurf --gemini --bob --hermes
+```
+
+Signs in, writes the servers, verifies them, and installs the three.ws skill for Claude Code, with no prompts. The config gets a `three-ws proxy` launcher, never a token: credentials stay in `~/.config/three-ws/credentials.json` (mode 600). Running it again changes nothing. Then: `claude "launch my agent"`.
+
+Hosted installers: `curl -fsSL https://three.ws/cli/install | sh` and `curl -fsSL https://three.ws/cli/claude | sh`. Every script ships with a `.sha256` checksum and an ed25519 `.sig`; download, read and verify before running: [three.ws/docs/cli#verify-before-you-run](https://three.ws/docs/cli#verify-before-you-run).
+
+```bash
+npx three-ws doctor # bad config, expired sign-in, unreachable server, with the fix for each
+npx three-ws agent status # agents, wallets and balances
+npx three-ws team # your teams; `team status <id>` for one
+```
+
+### Clean-container check
+
+`tests/container/run.sh` packs this package and, for each client, starts a fresh `node:22` container, runs the hosted installer against a local stand-in platform, and asserts the config is written without a key, a second run changes nothing, `doctor` passes and the credential file is mode 600. Needs Docker.
+
+```bash
+bash packages/three-ws-cli/tests/container/run.sh
+```
+
## Common commands
```bash
diff --git a/packages/three-ws-cli/src/commands/account.js b/packages/three-ws-cli/src/commands/account.js
index c55bfa554..1b4cdd2bc 100644
--- a/packages/three-ws-cli/src/commands/account.js
+++ b/packages/three-ws-cli/src/commands/account.js
@@ -67,6 +67,8 @@ export function scanClients(env, origin) {
const files = [];
for (const project of scopes) {
const file = client.configPath(env, { project });
+ // Run from the home directory, the project file IS the user file.
+ if (project && file === client.configPath(env, { project: false })) continue;
try {
const servers = readServers(client, env, { project });
const names = Object.entries(servers).filter(([name, entry]) => isThreeWsEntry(name, entry, origin)).map(([name, entry]) => ({ name, entry, project }));
diff --git a/packages/three-ws-cli/src/commands/setup.js b/packages/three-ws-cli/src/commands/setup.js
index 1dcc4479c..8e94daeca 100644
--- a/packages/three-ws-cli/src/commands/setup.js
+++ b/packages/three-ws-cli/src/commands/setup.js
@@ -178,7 +178,7 @@ export async function setup(ctx) {
for (const w of writes) {
if (w.error) line(` ${c.red(sym.fail)} ${w.client.label.padEnd(15)} ${w.error}`);
else {
- const viaProxy = servers.some((s) => usesProxy({ client: w.client, server: s, mode, forceProxy: flags.proxy })) ? c.dim(' (OAuth via the three-ws proxy)') : '';
+ const viaProxy = servers.some((s) => usesProxy({ client: w.client, server: s, mode, forceProxy: flags.proxy })) ? c.dim(mode === 'apikey' ? ' (via the three-ws proxy; the key stays in the credential store)' : ' (OAuth via the three-ws proxy)') : '';
line(` ${c.green(sym.ok)} ${w.client.label.padEnd(15)} ${tildify(w.file)} ${c.dim(`${w.servers.length} servers`)}${viaProxy}`);
}
}
diff --git a/packages/three-ws-cli/tests/container/platform-stub.mjs b/packages/three-ws-cli/tests/container/platform-stub.mjs
new file mode 100644
index 000000000..23bc94590
--- /dev/null
+++ b/packages/three-ws-cli/tests/container/platform-stub.mjs
@@ -0,0 +1,50 @@
+// A stand-in for the three.ws endpoints the installer path touches, so the clean
+// container test runs without a real account: whoami, the MCP directory, the
+// hosted skill file, one MCP server, and the signed installer scripts themselves.
+// Usage: node platform-stub.mjs <port>
+
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const port = Number(process.argv[2] || 8799);
+const origin = `http://127.0.0.1:${port}`;
+const json = (res, body, headers = {}) => {
+ res.writeHead(200, { 'content-type': 'application/json', ...headers });
+ res.end(JSON.stringify(body));
+};
+
+http.createServer((req, res) => {
+ const url = new URL(req.url, origin);
+ if (url.pathname === '/api/cli/whoami') return json(res, { user: { id: 'stub-user', email: '[email protected]' } });
+ if (url.pathname === '/.well-known/mcp.json') return json(res, { servers: [{ name: 'three.ws', endpoint: `${origin}/mcp`, transport: 'streamable-http', auth: 'oauth' }] });
+ if (url.pathname === '/skill.md') {
+ res.writeHead(200, { 'content-type': 'text/markdown' });
+ return res.end(fs.readFileSync(path.join(ROOT, 'public', 'skill.md')));
+ }
+ if (url.pathname.startsWith('/cli/')) {
+ const file = path.join(ROOT, 'public', url.pathname);
+ if (!file.startsWith(path.join(ROOT, 'public', 'cli')) || !fs.existsSync(file)) {
+ res.writeHead(404);
+ return res.end();
+ }
+ res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+ return res.end(fs.readFileSync(file));
+ }
+ if (url.pathname === '/mcp' && req.method === 'POST') {
+ let body = '';
+ req.on('data', (d) => (body += d));
+ req.on('end', () => {
+ const msg = JSON.parse(body);
+ if (msg.method === 'initialize') return json(res, { jsonrpc: '2.0', id: msg.id, result: { protocolVersion: '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'stub', version: '1' } } }, { 'mcp-session-id': 's' });
+ if (msg.method === 'tools/list') return json(res, { jsonrpc: '2.0', id: msg.id, result: { tools: [{ name: 'forge_free', inputSchema: { type: 'object' } }, { name: 'create_agent', inputSchema: { type: 'object' } }] } });
+ res.writeHead(202);
+ res.end();
+ });
+ return;
+ }
+ res.writeHead(404, { 'content-type': 'application/json' });
+ res.end('{"error":"not_found"}');
+}).listen(port, '127.0.0.1', () => console.log(`stub listening on ${origin}`));
diff --git a/packages/three-ws-cli/tests/container/run.sh b/packages/three-ws-cli/tests/container/run.sh
new file mode 100755
index 000000000..b07be8ad9
--- /dev/null
+++ b/packages/three-ws-cli/tests/container/run.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+# Clean-container check for every client config path: for each client, a fresh
+# node container (no config, no credentials) runs the real hosted installer
+# through `curl | sh` against a local stand-in platform, then asserts the client
+# config exists, holds no secret, survives a second run unchanged, and passes
+# `three-ws doctor`. Needs docker. Usage: sh run.sh (from anywhere)
+
+set -eu
+HERE="$(cd "$(dirname "$0")" && pwd)"
+PKG="$HERE/../.."
+PORT="${PORT:-8799}"
+WORK="$(mktemp -d)"
+KEY="sk_live_container_test_key_0000000000"
+IMAGE="${IMAGE:-node:22}"
+
+(cd "$PKG" && npm pack --silent --pack-destination "$WORK" >/dev/null)
+TARBALL="$(ls "$WORK"/three-ws-*.tgz)"
+node "$HERE/platform-stub.mjs" "$PORT" >/dev/null &
+STUB=$!
+trap 'kill $STUB 2>/dev/null; rm -rf "$WORK"' EXIT
+sleep 1
+
+CASES="claude:.claude.json cursor:.cursor/mcp.json windsurf:.codeium/windsurf/mcp_config.json codex:.codex/config.toml vscode:.config/Code/User/mcp.json gemini:.gemini/settings.json"
+FAILED=0
+for c in $CASES; do
+ flag="${c%%:*}"; rel="${c#*:}"
+ printf '== --%s ==\n' "$flag"
+ if docker run --rm --network host -v "$WORK:/pkg:ro" -e THREE_WS_API_KEY="$KEY" -e THREE_WS_PACKAGE=file:/pkg/"$(basename "$TARBALL")" \
+ -e THREE_WS_NO_BROWSER=1 "$IMAGE" sh -ec '
+ O=http://127.0.0.1:'"$PORT"'
+ cd "$HOME"
+ run() { curl -fsSL "$O/cli/install.sh" | sh -s -- -- --'"$flag"' --key --origin "$O" >/tmp/out 2>&1 || { cat /tmp/out; exit 1; }; }
+ run
+ test -f "'"$rel"'" || { echo "missing '"$rel"'"; exit 1; }
+ if grep -r "'"$KEY"'" "'"$rel"'" >/dev/null; then echo "secret written to client config"; exit 1; fi
+ cp "'"$rel"'" /tmp/first
+ run
+ cmp /tmp/first "'"$rel"'" || { echo "second run changed the file"; exit 1; }
+ npx --yes "$THREE_WS_PACKAGE" doctor --origin "$O" </dev/null
+ stat -c %a ~/.config/three-ws/credentials.json | grep -qx 600
+ '; then echo "ok --$flag"; else echo "FAIL --$flag"; FAILED=1; fi
+done
+exit $FAILED
diff --git a/packages/three-ws-cli/tests/quick-doctor.test.js b/packages/three-ws-cli/tests/quick-doctor.test.js
new file mode 100644
index 000000000..ffea2c834
--- /dev/null
+++ b/packages/three-ws-cli/tests/quick-doctor.test.js
@@ -0,0 +1,291 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { writeStore, readStore } from '../src/store.js';
+import { main, parse } from '../src/cli.js';
+import { clientsFromFlags } from '../src/commands/quick.js';
+import { checkNode, entryUrl } from '../src/commands/doctor.js';
+
+const ORIGIN = 'https://three.ws';
+const KEY = 'sk_live_cli_quick_test_key_000000000';
+const SKILL = '---\nname: three-ws\ndescription: test\n---\n\n# three.ws\n';
+
+function tempEnv() {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'three-ws-quick-'));
+ return { home, platform: process.platform, cwd: home, vars: { THREE_WS_NO_BROWSER: '1' } };
+}
+
+function reply(status, body, headers = {}) {
+ return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } });
+}
+
+async function run(argv, env) {
+ let out = '';
+ const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+ out += String(chunk);
+ return true;
+ });
+ const err = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+ try {
+ const code = await main(argv, env);
+ return { code, out, json: argv.includes('--json') && out ? JSON.parse(out) : null };
+ } finally {
+ write.mockRestore();
+ err.mockRestore();
+ }
+}
+
+/** The three.ws endpoints the quick path touches, answered like the real ones. */
+function platform({ skill = SKILL, toolsStatus = 200 } = {}) {
+ return vi.fn(async (url, init = {}) => {
+ const u = new URL(String(url));
+ if (u.pathname === '/api/cli/whoami') return reply(200, { user: { id: 'u1', email: '[email protected]' } });
+ if (u.pathname === '/.well-known/mcp.json') return reply(200, { servers: [{ name: 'three.ws', endpoint: `${ORIGIN}/mcp`, transport: 'streamable-http', auth: 'oauth' }] });
+ if (u.pathname === '/skill.md') return new Response(skill, { status: skill ? 200 : 404 });
+ if (u.pathname === '/mcp') {
+ if (toolsStatus !== 200) return reply(toolsStatus, { error: 'unauthorized' });
+ const msg = JSON.parse(init.body);
+ if (msg.method === 'initialize') return reply(200, { jsonrpc: '2.0', id: msg.id, result: { protocolVersion: '2025-06-18', capabilities: {}, serverInfo: { name: 'three-ws', version: '1' } } }, { 'mcp-session-id': 's' });
+ if (msg.method === 'tools/list') return reply(200, { jsonrpc: '2.0', id: msg.id, result: { tools: [{ name: 'forge_free' }, { name: 'create_agent' }] } });
+ return new Response(null, { status: 202 });
+ }
+ return reply(404, { error: 'not_found' });
+ });
+}
+
+describe('per-client flags', () => {
+ it('turn a bare flag into the whole setup for that client', () => {
+ expect(parse(['--claude']).command).toBe('quick');
+ expect(parse(['--cursor', '--codex']).command).toBe('quick');
+ expect(parse(['setup', '--vscode']).command).toBe('quick');
+ expect(parse(['status']).command).toBe('status');
+ expect(parse([]).command).toBe('help');
+ expect(clientsFromFlags(parse(['--windsurf', '--claude']).flags)).toEqual(['claude-code', 'windsurf']);
+ });
+});
+
+describe('three-ws --<client> on a clean home', () => {
+ let env;
+ let fetchMock;
+ beforeEach(() => {
+ env = tempEnv();
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ fetchMock = platform();
+ vi.stubGlobal('fetch', fetchMock);
+ });
+ afterEach(() => vi.unstubAllGlobals());
+
+ const CASES = [
+ ['--claude', () => '.claude.json', 'mcpServers'],
+ ['--cursor', () => path.join('.cursor', 'mcp.json'), 'mcpServers'],
+ ['--windsurf', () => path.join('.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers'],
+ ['--gemini', () => path.join('.gemini', 'settings.json'), 'mcpServers'],
+ ['--bob', () => path.join('.bob', 'settings', 'mcp.json'), 'mcpServers'],
+ ];
+
+ for (const [flag, rel, root] of CASES) {
+ it(`${flag} writes the client config, verifies it live and stores no secret in it`, async () => {
+ const { code, json } = await run([flag, '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ expect(json.clients.every((c) => !c.error)).toBe(true);
+ const file = path.join(env.home, rel());
+ const text = fs.readFileSync(file, 'utf8');
+ expect(Object.keys(JSON.parse(text)[root])).toContain('three-ws');
+ expect(text).not.toContain(KEY);
+ expect(text).toContain('"proxy"');
+ });
+ }
+
+ it('--codex and --vscode write their own formats without the key', async () => {
+ let r = await run(['--codex', '--json', '--origin', ORIGIN], env);
+ expect(r.code).toBe(0);
+ const toml = fs.readFileSync(path.join(env.home, '.codex', 'config.toml'), 'utf8');
+ expect(toml).toContain('mcp_servers');
+ expect(toml).not.toContain(KEY);
+ r = await run(['--vscode', '--json', '--origin', ORIGIN], env);
+ expect(r.code).toBe(0);
+ const vs = fs.readFileSync(path.join(env.home, '.config', 'Code', 'User', 'mcp.json'), 'utf8');
+ expect(JSON.parse(vs).servers['three-ws']).toBeTruthy();
+ expect(vs).not.toContain(KEY);
+ });
+
+ it('is idempotent: a second run leaves the same file and one entry', async () => {
+ await run(['--cursor', '--json', '--origin', ORIGIN], env);
+ const file = path.join(env.home, '.cursor', 'mcp.json');
+ const first = fs.readFileSync(file, 'utf8');
+ await run(['--cursor', '--json', '--origin', ORIGIN], env);
+ expect(fs.readFileSync(file, 'utf8')).toBe(first);
+ });
+
+ it('--claude installs the skill once and leaves it alone afterwards', async () => {
+ await run(['--claude', '--origin', ORIGIN], env);
+ const skill = path.join(env.home, '.claude', 'skills', 'three-ws', 'SKILL.md');
+ expect(fs.readFileSync(skill, 'utf8')).toBe(SKILL);
+ const before = fs.statSync(skill).mtimeMs;
+ await new Promise((r) => setTimeout(r, 15));
+ await run(['--claude', '--origin', ORIGIN], env);
+ expect(fs.statSync(skill).mtimeMs).toBe(before);
+ });
+
+ it('--claude fails loudly when the skill file is not a three.ws skill', async () => {
+ vi.stubGlobal('fetch', platform({ skill: '<html>oops</html>' }));
+ const { code } = await run(['--claude', '--origin', ORIGIN], env);
+ expect(code).toBe(1);
+ expect(fs.existsSync(path.join(env.home, '.claude', 'skills'))).toBe(false);
+ });
+
+ it('keeps the credential store owner-only and the key out of every written file', async () => {
+ await run(['--claude', '--cursor', '--origin', ORIGIN], env);
+ const store = path.join(env.home, '.config', 'three-ws', 'credentials.json');
+ if (process.platform !== 'win32') expect(fs.statSync(store).mode & 0o077).toBe(0);
+ expect(readStore(env).auth.key).toBe(KEY);
+ for (const f of ['.claude.json', path.join('.cursor', 'mcp.json')]) {
+ expect(fs.readFileSync(path.join(env.home, f), 'utf8')).not.toContain(KEY);
+ }
+ });
+});
+
+describe('three-ws doctor', () => {
+ let env;
+ afterEach(() => vi.unstubAllGlobals());
+ beforeEach(() => {
+ env = tempEnv();
+ });
+
+ it('checkNode passes current Node and rejects an old one', () => {
+ expect(checkNode('24.1.0').status).toBe('ok');
+ expect(checkNode('20.12.0').status).toBe('ok');
+ expect(checkNode('20.11.9').status).toBe('fail');
+ expect(checkNode('18.19.0').status).toBe('fail');
+ });
+
+ it('entryUrl reads direct and proxied entries', () => {
+ expect(entryUrl({ url: `${ORIGIN}/mcp` })).toBe(`${ORIGIN}/mcp`);
+ expect(entryUrl({ command: 'npx', args: ['-y', 'three-ws', 'proxy', `${ORIGIN}/mcp`, '--server', 'three-ws'] })).toBe(`${ORIGIN}/mcp`);
+ expect(entryUrl({ command: 'x', args: [] })).toBeNull();
+ });
+
+ it('reports a healthy setup and exits 0', async () => {
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ vi.stubGlobal('fetch', platform());
+ await run(['--cursor', '--origin', ORIGIN], env);
+ const { code, json } = await run(['doctor', '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ expect(json.failed).toBe(0);
+ expect(json.checks.some((c) => c.id.startsWith('server:') && c.status === 'ok')).toBe(true);
+ });
+
+ it('flags a signed-out machine, a broken config and a plain-text key, each with a fix', async () => {
+ vi.stubGlobal('fetch', platform());
+ const cursor = path.join(env.home, '.cursor', 'mcp.json');
+ fs.mkdirSync(path.dirname(cursor), { recursive: true });
+ fs.writeFileSync(cursor, JSON.stringify({ mcpServers: { 'three-ws': { url: `${ORIGIN}/mcp`, headers: { Authorization: `Bearer ${KEY}` } } } }));
+ const codex = path.join(env.home, '.codex', 'config.toml');
+ fs.mkdirSync(path.dirname(codex), { recursive: true });
+ fs.writeFileSync(codex, 'this is = = not toml');
+ const { code, json } = await run(['doctor', '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(1);
+ const byId = Object.fromEntries(json.checks.map((c) => [c.id, c]));
+ expect(byId.auth.status).toBe('fail');
+ expect(byId['secret:cursor:three-ws'].status).toBe('warn');
+ expect(byId['client:codex'].status).toBe('fail');
+ expect(json.checks.filter((c) => c.status !== 'ok').every((c) => c.fix)).toBe(true);
+ });
+
+ it('reports an expired session that cannot refresh', async () => {
+ writeStore({ origin: ORIGIN, auth: { type: 'oauth', access_token: 'old', expires_at: Date.now() - 60_000, scope: 'profile' } }, env);
+ vi.stubGlobal('fetch', platform());
+ const { json } = await run(['doctor', '--json', '--origin', ORIGIN], env);
+ const auth = json.checks.find((c) => c.id === 'auth');
+ expect(auth.status).toBe('fail');
+ expect(auth.fix).toContain('login');
+ });
+
+ it('reports an unreachable server', async () => {
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ const ok = platform();
+ vi.stubGlobal('fetch', ok);
+ await run(['--cursor', '--origin', ORIGIN], env);
+ vi.stubGlobal('fetch', vi.fn(async (url) => {
+ if (new URL(String(url)).pathname === '/mcp') throw new TypeError('fetch failed');
+ return ok(url);
+ }));
+ const { code, json } = await run(['doctor', '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(1);
+ expect(json.checks.find((c) => c.id === `server:${ORIGIN}/mcp`).status).toBe('fail');
+ });
+});
+
+describe('three-ws agent status and team', () => {
+ let env;
+ beforeEach(() => {
+ env = tempEnv();
+ writeStore({ origin: ORIGIN, auth: { type: 'apikey', key: KEY, prefix: KEY.slice(0, 12) } }, env);
+ });
+ afterEach(() => vi.unstubAllGlobals());
+
+ it('agent status joins the agent list with live balances', async () => {
+ const calls = [];
+ vi.stubGlobal('fetch', vi.fn(async (url, init = {}) => {
+ const u = new URL(String(url));
+ calls.push(`${init.method || 'GET'} ${u.pathname}`);
+ if (u.pathname === '/api/agents') return reply(200, { agents: [{ id: '11111111-1111-4111-8111-111111111111', name: 'Nova', avatar_id: 'av1', solana_address: 'So1anaAddre55', walletReady: true }] });
+ if (u.pathname === '/api/agents/balances') return reply(200, { data: { '11111111-1111-4111-8111-111111111111': { sol: 1.5, usdc: 20, usd: 250 } } });
+ return reply(404, {});
+ }));
+ const { code, json } = await run(['agent', 'status', '--json', '--origin', ORIGIN], env);
+ expect(code).toBe(0);
+ expect(json.agents[0]).toMatchObject({ name: 'Nova', sol: 1.5, usdc: 20, usd: 250, has_body: true });
+ expect(calls).toEqual(['GET /api/agents', 'POST /api/agents/balances']);
+ });
+
+ it('agent status names the unknown agent instead of printing nothing', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => reply(200, { agents: [] })));
+ const { code } = await run(['agent', 'status', 'ghost', '--origin', ORIGIN], env);
+ expect(code).toBe(1);
+ });
+
+ it('team lists teams and team status shows one with its roster', async () => {
+ const team = { id: 't1', name: 'Alpha', status: 'active', network: 'devnet', member_count: 1, last_finding_at: null, roster: [{ role: 'researcher', name: 'Rex' }] };
+ vi.stubGlobal('fetch', vi.fn(async (url) => {
+ const p = new URL(String(url)).pathname;
+ if (p === '/api/teams') return reply(200, { data: [team] });
+ if (p === '/api/teams/t1') return reply(200, { data: { ...team, page_url: '/teams/t1', findings: { total: 3, last_24h: 1, last_at: null }, missing_roles: ['launcher'], last_error: null, trader_balance_sol: 0.25, members: [{ role: 'researcher', agent: { name: 'Rex', wallet: 'So1anaAddre55' } }] } });
+ return reply(404, {});
+ }));
+ let r = await run(['team', '--json', '--origin', ORIGIN], env);
+ expect(r.json.teams[0].name).toBe('Alpha');
+ r = await run(['team', 'status', 'alpha', '--json', '--origin', ORIGIN], env);
+ expect(r.code).toBe(0);
+ expect(r.json.team.missing_roles).toEqual(['launcher']);
+ });
+
+ it('both ask you to sign in when there is no credential', async () => {
+ const bare = tempEnv();
+ const a = await run(['agent', 'status', '--origin', ORIGIN], bare);
+ const t = await run(['team', '--origin', ORIGIN], bare);
+ expect([a.code, t.code]).toEqual([1, 1]);
+ });
+});
+
+describe('hosted installer scripts', () => {
+ const dir = path.resolve(import.meta.dirname, '../../../public/cli');
+ const pub = crypto.createPublicKey(fs.readFileSync(path.join(dir, 'signing-key.pem')));
+
+ for (const name of ['install.sh', 'claude.sh']) {
+ it(`${name} matches its published checksum and signature`, () => {
+ const bytes = fs.readFileSync(path.join(dir, name));
+ const sum = fs.readFileSync(path.join(dir, `${name}.sha256`), 'utf8').trim();
+ expect(sum).toBe(`${crypto.createHash('sha256').update(bytes).digest('hex')} ${name}`);
+ expect(crypto.verify(null, bytes, pub, fs.readFileSync(path.join(dir, `${name}.sig`)))).toBe(true);
+ });
+
+ it(`${name} runs nothing until the whole file has been read, and never touches credentials`, () => {
+ const text = fs.readFileSync(path.join(dir, name), 'utf8');
+ expect(text.trimEnd().endsWith('main "$@"')).toBe(true);
+ expect(text).not.toMatch(/credentials\.json|sudo |\.bashrc|\.zshrc|\.profile/);
+ });
+ }
+});
diff --git a/pages/connect.html b/pages/connect.html
index 03967e2d5..50e0056bb 100644
--- a/pages/connect.html
+++ b/pages/connect.html
@@ -320,6 +320,11 @@
<li data-i18n-html="connect.run_the_command_add_to_share_it">Run the command. Add <code>--scope project</code> to share it with your team through <code>.mcp.json</code>.</li>
<li data-i18n-html="connect.in_claude_code_type_pick_the_server">In Claude Code, type <code>/mcp</code>, pick the server you just added and choose <strong>Authenticate</strong>.</li>
</ol>
+ <p class="cn-panel-lede" data-i18n-html="connect.or_let_one_script_do_all_of_it">Or let one command do all of it: it signs you in, writes the server and the three.ws skill, and keeps every key out of your config file. <a href="/docs/cli#verify-before-you-run">Read the script and check its signature first</a>.</p>
+ <div class="cn-snippet">
+ <div class="cn-snippet-head"><span data-i18n="connect.terminal">Terminal</span><button type="button" class="cn-btn" data-copy-target="cn-cc-quick" data-i18n="connect.copy">Copy</button></div>
+ <pre><code id="cn-cc-quick">npx three-ws --claude</code></pre>
+ </div>
</div>
<div class="cn-panel" role="tabpanel" id="panel-cursor" aria-labelledby="tab-cursor" tabindex="0" hidden>
diff --git a/public/cli/claude.sh b/public/cli/claude.sh
new file mode 100644
index 000000000..f4d62e7dd
--- /dev/null
+++ b/public/cli/claude.sh
@@ -0,0 +1,93 @@
+#!/bin/sh
+# three.ws for Claude Code: https://three.ws/cli/claude
+#
+# Wires the three.ws MCP servers and the three.ws skill into Claude Code, then
+# offers to launch it. Read it first, verify it, then run it:
+# curl -fsSLO https://three.ws/cli/claude.sh
+# curl -fsSLO https://three.ws/cli/claude.sh.sha256
+# curl -fsSLO https://three.ws/cli/claude.sh.sig
+# (checksum and signature steps: https://three.ws/docs/cli#verify-before-you-run)
+# sh claude.sh
+#
+# What it does: runs `npx three-ws --claude`, which signs you in through your
+# browser (add --device over SSH), adds the servers to ~/.claude.json through the
+# local proxy (no key or token is written into that file), and installs the skill
+# to ~/.claude/skills/three-ws/SKILL.md. It does not use sudo, edit shell profiles
+# or install anything globally. Running it again changes nothing.
+#
+# Usage: sh claude.sh [--launch | --no-launch] [--project] [--device] [--key]
+# --launch start `claude "launch my agent"` when setup succeeds, without asking
+# --no-launch never offer to launch
+# --project write ./.mcp.json and ./.claude/skills instead of the user-level files
+# --device sign in by approving a code in any browser (works over SSH)
+# --key sign in with an API key from THREE_WS_API_KEY
+# Environment: THREE_WS_VERSION pins a version of the CLI (default: latest).
+# THREE_WS_PACKAGE replaces the whole npm spec (a private mirror, or a tarball when testing).
+
+set -eu
+
+MIN_NODE_MAJOR=20
+MIN_NODE_MINOR=12
+PROMPT_TEXT="launch my agent"
+
+say() { printf '%s\n' "$*"; }
+fail() { printf 'three-ws claude: %s\n' "$*" >&2; exit 1; }
+
+check_node() {
+ command -v node >/dev/null 2>&1 || fail "Node.js is not installed. Install $MIN_NODE_MAJOR.$MIN_NODE_MINOR or newer from https://nodejs.org, then run this again."
+ v="$(node -p 'process.versions.node')"
+ major="${v%%.*}"
+ rest="${v#*.}"
+ minor="${rest%%.*}"
+ if [ "$major" -lt "$MIN_NODE_MAJOR" ] || { [ "$major" -eq "$MIN_NODE_MAJOR" ] && [ "$minor" -lt "$MIN_NODE_MINOR" ]; }; then
+ fail "Node.js $v is too old; three-ws needs $MIN_NODE_MAJOR.$MIN_NODE_MINOR or newer."
+ fi
+ command -v npx >/dev/null 2>&1 || fail "npx was not found next to Node.js. Reinstall Node.js from https://nodejs.org."
+}
+
+check_claude() {
+ command -v claude >/dev/null 2>&1 || fail "Claude Code is not installed. Install it first (https://docs.claude.com/en/docs/claude-code), then run this again."
+}
+
+ask_launch() {
+ # stdin is the script itself under `curl | sh`, so ask on the terminal. No
+ # terminal (CI, a pipe): never launch an interactive program by surprise.
+ [ -r /dev/tty ] && [ -w /dev/tty ] || return 1
+ printf 'Start Claude Code now with: claude "%s"? [y/N] ' "$PROMPT_TEXT" >/dev/tty
+ read -r reply </dev/tty || return 1
+ case "$reply" in y|Y|yes|YES) return 0 ;; *) return 1 ;; esac
+}
+
+main() {
+ LAUNCH=ask
+ PASS=""
+ while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --launch) LAUNCH=yes ;;
+ --no-launch) LAUNCH=no ;;
+ --project|--device|--key) PASS="$PASS $1" ;;
+ --help|-h) sed -n '2,25p' "$0" 2>/dev/null || say "See https://three.ws/docs/cli"; return 0 ;;
+ *) fail "unknown option $1" ;;
+ esac
+ shift
+ done
+
+ check_node
+ check_claude
+
+ # shellcheck disable=SC2086
+ npx --yes "${THREE_WS_PACKAGE:-three-ws@${THREE_WS_VERSION:-latest}}" --claude $PASS </dev/null || fail "setup did not finish. Run \`npx three-ws doctor\` to see what is wrong."
+
+ say ""
+ say "Claude Code is wired to three.ws. Restart it to load the tools."
+ say " Start with: claude \"$PROMPT_TEXT\""
+ say " Check later: npx three-ws doctor"
+
+ case "$LAUNCH" in
+ yes) exec claude "$PROMPT_TEXT" ;;
+ ask) if ask_launch; then exec claude "$PROMPT_TEXT"; fi ;;
+ esac
+}
+
+# Nothing runs until the whole file has arrived (see install.sh).
+main "$@"
diff --git a/public/cli/claude.sh.sha256 b/public/cli/claude.sh.sha256
new file mode 100644
index 000000000..639f9690d
--- /dev/null
+++ b/public/cli/claude.sh.sha256
@@ -0,0 +1 @@
+cb50d9c6aa6ce5f1c38de0bf89c13a4237d4ca2aad12db8494435ed00d26563f claude.sh
diff --git a/public/cli/claude.sh.sig b/public/cli/claude.sh.sig
new file mode 100644
index 000000000..88073770f
--- /dev/null
+++ b/public/cli/claude.sh.sig
@@ -0,0 +1,2 @@
+,_�g��욵����
+=ɀe�@Õ��S�L@��������' ��D�|��t��ȵb�o�
\ No newline at end of file
diff --git a/public/cli/install.sh b/public/cli/install.sh
new file mode 100644
index 000000000..25055bb57
--- /dev/null
+++ b/public/cli/install.sh
@@ -0,0 +1,116 @@
+#!/bin/sh
+# three.ws CLI installer: https://three.ws/cli/install
+#
+# Checks your OS and Node.js, then installs or runs the three-ws CLI and prints
+# what to do next. Read it first, verify it, then run it:
+# curl -fsSLO https://three.ws/cli/install.sh
+# curl -fsSLO https://three.ws/cli/install.sh.sha256
+# curl -fsSLO https://three.ws/cli/install.sh.sig
+# (checksum and signature steps: https://three.ws/docs/cli#verify-before-you-run)
+# sh install.sh
+#
+# What it does NOT do: use sudo, edit shell profiles, read or write credentials,
+# or install Node.js for you. It is safe to run again; a second run changes nothing.
+#
+# Usage: sh install.sh [--global] [--no-run] [-- <three-ws arguments>]
+# --global install the CLI with `npm install -g` instead of running it through npx
+# --no-run only check and install, then print the next steps
+# anything after `--` is passed to three-ws, e.g. `-- --cursor`
+# Environment: THREE_WS_VERSION pins a version (default: latest). THREE_WS_PACKAGE
+# replaces the whole npm spec (a private mirror, or a local tarball when testing).
+
+set -eu
+
+MIN_NODE_MAJOR=20
+MIN_NODE_MINOR=12
+PACKAGE="three-ws"
+SPEC="${THREE_WS_PACKAGE:-$PACKAGE@${THREE_WS_VERSION:-latest}}"
+
+say() { printf '%s\n' "$*"; }
+fail() { printf 'three-ws install: %s\n' "$*" >&2; exit 1; }
+
+check_os() {
+ case "$(uname -s 2>/dev/null || echo unknown)" in
+ Linux) OS=linux ;;
+ Darwin) OS=macos ;;
+ MINGW*|MSYS*|CYGWIN*) fail "this script needs a POSIX shell. On Windows run it in WSL, or use PowerShell: npx three-ws setup" ;;
+ *) fail "unsupported OS $(uname -s). Run \`npx three-ws setup\` directly if you have Node.js $MIN_NODE_MAJOR.$MIN_NODE_MINOR or newer." ;;
+ esac
+}
+
+check_node() {
+ command -v node >/dev/null 2>&1 || fail "Node.js is not installed. Install version $MIN_NODE_MAJOR.$MIN_NODE_MINOR or newer from https://nodejs.org (or with nvm / fnm / Homebrew), then run this again."
+ NODE_VERSION="$(node -p 'process.versions.node')"
+ major="${NODE_VERSION%%.*}"
+ rest="${NODE_VERSION#*.}"
+ minor="${rest%%.*}"
+ if [ "$major" -lt "$MIN_NODE_MAJOR" ] || { [ "$major" -eq "$MIN_NODE_MAJOR" ] && [ "$minor" -lt "$MIN_NODE_MINOR" ]; }; then
+ fail "Node.js $NODE_VERSION is too old; three-ws needs $MIN_NODE_MAJOR.$MIN_NODE_MINOR or newer. Update it from https://nodejs.org and run this again."
+ fi
+ command -v npm >/dev/null 2>&1 || fail "npm was not found next to Node.js. Reinstall Node.js from https://nodejs.org."
+}
+
+install_global() {
+ want="${THREE_WS_VERSION:-latest}"
+ [ -z "${THREE_WS_PACKAGE:-}" ] || want="custom"
+ have="$(npm ls -g --depth=0 --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).dependencies["three-ws"].version)}catch{console.log("")}})')"
+ if [ -n "$have" ] && { [ "$want" = "latest" ] || [ "$want" = "$have" ]; }; then
+ latest="$(npm view "$PACKAGE" version 2>/dev/null || echo "$have")"
+ if [ "$want" != "latest" ] || [ "$latest" = "$have" ]; then
+ say "three-ws $have is already installed."
+ return 0
+ fi
+ fi
+ say "Installing $SPEC globally with npm..."
+ npm install -g "$SPEC" >/dev/null || fail "npm install -g failed. If it is a permissions error, use a Node version manager (nvm, fnm) or run without --global."
+ say "Installed three-ws $(three-ws version 2>/dev/null || echo "$want")."
+}
+
+run_cli() {
+ if [ "$GLOBAL" = 1 ] && command -v three-ws >/dev/null 2>&1; then
+ three-ws "$@" </dev/null
+ else
+ npx --yes "$SPEC" "$@" </dev/null
+ fi
+}
+
+next_steps() {
+ say ""
+ say "Next steps"
+ say " npx three-ws --claude Claude Code (MCP servers and the three.ws skill)"
+ say " npx three-ws --cursor Cursor (also --codex, --vscode, --windsurf)"
+ say " npx three-ws setup pick clients and servers interactively"
+ say " npx three-ws doctor diagnose a setup that is not working"
+ say "Docs: https://three.ws/docs/cli"
+}
+
+main() {
+ GLOBAL=0
+ RUN=1
+ while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --global) GLOBAL=1 ;;
+ --no-run) RUN=0 ;;
+ --help|-h) sed -n '2,23p' "$0" 2>/dev/null || say "See https://three.ws/docs/cli"; return 0 ;;
+ --) shift; break ;;
+ *) fail "unknown option $1 (pass three-ws arguments after --)" ;;
+ esac
+ shift
+ done
+
+ check_os
+ check_node
+ say "OS: $OS, Node.js $NODE_VERSION: ok"
+
+ if [ "$GLOBAL" = 1 ]; then install_global; fi
+
+ if [ "$#" -gt 0 ] && [ "$RUN" = 1 ]; then
+ run_cli "$@"
+ return $?
+ fi
+ next_steps
+}
+
+# Everything above only defines functions. Nothing runs until the whole file has
+# arrived, so a download cut off halfway can never execute half a script.
+main "$@"
diff --git a/public/cli/install.sh.sha256 b/public/cli/install.sh.sha256
new file mode 100644
index 000000000..0d0d44607
--- /dev/null
+++ b/public/cli/install.sh.sha256
@@ -0,0 +1 @@
+9771481e630949ee23c910e584ff88e7d17a4f50ca863bf5c4fed166b0d7053a install.sh
diff --git a/public/cli/install.sh.sig b/public/cli/install.sh.sig
new file mode 100644
index 000000000..78d38e7e1
--- /dev/null
+++ b/public/cli/install.sh.sig
@@ -0,0 +1 @@
+Խ��Jy��>r�� �banS��wZ�jt��M�����{�*_�'�!��7�Z&�?+ɖ?W�2�
\ No newline at end of file
diff --git a/public/cli/signing-key.pem b/public/cli/signing-key.pem
new file mode 100644
index 000000000..7d3b85e2e
--- /dev/null
+++ b/public/cli/signing-key.pem
@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAE6siNFeWXW/+fzSxhRj0c687yIcQki2nMLqm51QMVPc=
+-----END PUBLIC KEY-----
diff --git a/scripts/sign-cli-scripts.mjs b/scripts/sign-cli-scripts.mjs
new file mode 100644
index 000000000..d7615bc9f
--- /dev/null
+++ b/scripts/sign-cli-scripts.mjs
@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Checksums and detached ed25519 signatures for the hosted CLI scripts
+// (public/cli/*.sh), so anyone piping them to a shell can verify first.
+//
+// node scripts/sign-cli-scripts.mjs --init [--out <dir>] make a keypair; the public half lands in public/cli/signing-key.pem
+// node scripts/sign-cli-scripts.mjs sign every script (key: THREE_WS_CLI_SIGNING_KEY pem text, or --key <file>)
+// node scripts/sign-cli-scripts.mjs --check verify checksums and signatures against the committed public key (no secret needed)
+//
+// For each public/cli/<name>.sh this writes <name>.sh.sha256 (sha256sum format) and
+// <name>.sh.sig (the raw 64-byte signature of the file's exact bytes). The private
+// key never lives in the repo; keep it in Secret Manager or the release machine.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIR = path.join(ROOT, 'public', 'cli');
+const PUB = path.join(DIR, 'signing-key.pem');
+
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const value = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : null);
+
+const scripts = () => fs.readdirSync(DIR).filter((f) => f.endsWith('.sh')).sort();
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+export function fingerprint(pubPem) {
+ const der = crypto.createPublicKey(pubPem).export({ type: 'spki', format: 'der' });
+ return sha256(der);
+}
+
+function init() {
+ const outDir = path.resolve(value('--out') || path.join(process.env.HOME || '.', '.config', 'three-ws-release'));
+ const keyFile = path.join(outDir, 'cli-signing-key.pem');
+ if (fs.existsSync(keyFile) || fs.existsSync(PUB)) {
+ console.error(`refusing to replace an existing key (${fs.existsSync(keyFile) ? keyFile : PUB}); rotate on purpose by deleting it first`);
+ return 1;
+ }
+ const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+ fs.mkdirSync(outDir, { recursive: true, mode: 0o700 });
+ fs.writeFileSync(keyFile, privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
+ fs.writeFileSync(PUB, publicKey.export({ type: 'spki', format: 'pem' }));
+ console.log(`private key: ${keyFile} (keep it out of the repo)\npublic key: ${path.relative(ROOT, PUB)}\nfingerprint: ${fingerprint(fs.readFileSync(PUB, 'utf8'))}`);
+ return 0;
+}
+
+function sign() {
+ const pem = process.env.THREE_WS_CLI_SIGNING_KEY || (value('--key') && fs.readFileSync(value('--key'), 'utf8'));
+ if (!pem) {
+ console.error('no signing key: set THREE_WS_CLI_SIGNING_KEY to the PEM text, or pass --key <file>');
+ return 1;
+ }
+ const key = crypto.createPrivateKey(pem);
+ const pub = fs.readFileSync(PUB, 'utf8');
+ if (fingerprint(crypto.createPublicKey(key).export({ type: 'spki', format: 'pem' })) !== fingerprint(pub)) {
+ console.error('that private key does not match public/cli/signing-key.pem');
+ return 1;
+ }
+ for (const name of scripts()) {
+ const bytes = fs.readFileSync(path.join(DIR, name));
+ fs.writeFileSync(path.join(DIR, `${name}.sha256`), `${sha256(bytes)} ${name}\n`);
+ fs.writeFileSync(path.join(DIR, `${name}.sig`), crypto.sign(null, bytes, key));
+ console.log(`signed ${name}`);
+ }
+ return 0;
+}
+
+/** Problems with the committed checksums and signatures; an empty list means all good. */
+export function verifyAll(dir = DIR) {
+ const problems = [];
+ let pub;
+ try {
+ pub = crypto.createPublicKey(fs.readFileSync(path.join(dir, 'signing-key.pem')));
+ } catch (err) {
+ return [`cannot read signing-key.pem: ${err.message}`];
+ }
+ const names = fs.readdirSync(dir).filter((f) => f.endsWith('.sh')).sort();
+ if (!names.length) problems.push('no scripts found');
+ for (const name of names) {
+ const bytes = fs.readFileSync(path.join(dir, name));
+ let sum = '';
+ try { sum = fs.readFileSync(path.join(dir, `${name}.sha256`), 'utf8').trim(); } catch { problems.push(`${name}.sha256 is missing`); }
+ if (sum && sum !== `${sha256(bytes)} ${name}`) problems.push(`${name}.sha256 does not match the file; re-run npm run sign:cli`);
+ let sig = null;
+ try { sig = fs.readFileSync(path.join(dir, `${name}.sig`)); } catch { problems.push(`${name}.sig is missing`); }
+ if (sig && !crypto.verify(null, bytes, pub, sig)) problems.push(`${name}.sig is not a valid signature of the file; re-run npm run sign:cli`);
+ }
+ return problems;
+}
+
+function check() {
+ const problems = verifyAll();
+ for (const p of problems) console.error(p);
+ if (!problems.length) console.log(`${scripts().length} script(s) verified, key ${fingerprint(fs.readFileSync(PUB, 'utf8')).slice(0, 16)}`);
+ return problems.length ? 1 : 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ process.exitCode = flag('--init') ? init() : flag('--check') ? check() : sign();
+}
diff --git a/vercel.json b/vercel.json
index 3cca4e047..67ba75396 100644
--- a/vercel.json
+++ b/vercel.json
@@ -563,6 +563,31 @@
"src": "/changelog/([^.]+)",
"dest": "/changelog/entry/index.html"
},
+ {
+ "src": "/cli/(install|claude)(?:\\.sh)?",
+ "headers": {
+ "content-type": "text/plain; charset=utf-8",
+ "cache-control": "public, max-age=300",
+ "x-content-type-options": "nosniff"
+ },
+ "dest": "/cli/$1.sh"
+ },
+ {
+ "src": "/cli/(install|claude)\\.sh\\.sha256",
+ "headers": {
+ "content-type": "text/plain; charset=utf-8",
+ "cache-control": "public, max-age=300"
+ },
+ "dest": "/cli/$1.sh.sha256"
+ },
+ {
+ "src": "/cli/signing-key\\.pem",
+ "headers": {
+ "content-type": "text/plain; charset=utf-8",
+ "cache-control": "public, max-age=3600"
+ },
+ "dest": "/cli/signing-key.pem"
+ },
{
"src": "/changelog\\.json",
"headers": {