feat: local npx deployment for Scope (server + standalone CLI)

[Cedric Vidal (cedricvidal)]

Lets someone try Scope on their laptop with two commands and no checkout:

npm install -g --omit=optional ./scope-server-0.1.0.tgz
scope-server start

That brings up the full platform — MongoDB, Redis, Azurite, Lowkey Vault, the API, Portal, Judge, scheduler, post-processor, report generator and the capture gateway — prints a Portal and API URL, and runs real benchmarks against real coding agents.

This is a third deployment option alongside the existing Compose development setup and the Kubernetes deployment. Neither of those changes.

How it works

apps/server/ — the launcher. A Commander CLI (start, stop, restart, status) that owns the local stack. It declares the services as a small typed manifest and drives Docker through packages/docker-orchestrator/ (Dockerode) rather than shelling out to docker compose. Every container and network it creates carries a dev.scope.server.owner label, so shutdown removes exactly what it created and never the persistent bind-mounted data. Ports are allocated once and reused on later starts, so saved CLI environments and bookmarks keep working.

Packaging. pnpm pack:server bundles version-matched Scope sources, Dockerfiles, the lockfile and config assets into a private tarball. Images are built locally on first run from those bundled sources — the package never checks out Scope or pulls a prebuilt Scope image. Only public dependencies and base images are fetched. Image cache keys include the sources, package version, build timestamp and component versions.

Host coding agents. Alongside the Docker workers, two new packages (coder-acp-copilot-host, coder-acp-claude-code-host) run the user's already installed Copilot or Claude Code CLI as a benchmark worker, reusing its existing login. Scope never installs, upgrades or logs into those CLIs. Host targets require explicit per-target consent that states what it means: the agent runs as you, with your files and login. To keep results reproducible, host runs disable personal MCP servers and settings (settingSources: [] + --strict-mcp-config for Claude; --disable-builtin-mcps plus per-server disables for Copilot) while deliberately not relocating HOME or CLAUDE_CONFIG_DIR, which would break login reuse.

To make this possible, each worker's queue-processing logic moved out of its index.ts entrypoint into a reusable worker.ts, so the Docker and host entrypoints share one implementation.

apps/cli/ — a standalone client. Packaged separately so it can be installed on its own. Adds named environments (scope env add/use/set), so one CLI can target the local instance and a shared deployment without re-typing URLs, with explicit precedence between flags, the named environment and process env. Also adds scope agent setup for enabling agents from the terminal, and scope secret for credential management — which the CLI previously lacked entirely, a CLI↔Portal parity gap. A regression test pins that no secret subcommand can print a credential value in any output format.

Portal. A Set up local agents dialog (ServerAgentSetup) appears only when the launcher is driving the API, offering the same host/Docker agent setup, executable selection and consent as the CLI.

Try it

scope env add local --url http://127.0.0.1:<printed-port>
scope env use local
scope agent setup coder-acp-copilot --enable --wait
scope run submit --worker coder-acp-copilot --model gpt-5.4-mini \
  --criteria <criterion> --message "<task>"

Logs stream live; results, artifacts and reports are available from both the CLI and the Portal. Stopping leaves the data directory intact, so a later scope-server start resumes with the same projects, runs and verdicts.

Also in here

• Capture backend default. createProxyClient() defaulted to the legacy devproxy when PROXY_BACKEND was unset, so any caller that forgot to set it silently got the legacy path. The default is now gateway, paired in the same commit with an explicit PROXY_BACKEND: devproxy pin for the ACP Claude Code worker in docker-compose.yml, which was relying on that implicit default. Behaviour-preserving for existing workers.
• Docker streaming. Image build/pull streams no longer inherit the management socket's inactivity timeout — quietly committing a large layer could exceed it and abort the build.
• Shutdown. Bounded graceful stop with forced removal of the already ownership-verified container, so a hung daemon can't leave orphans behind.

Validation

Exercised outside the checkout with the packed artifacts, on macOS arm64 with a Podman Docker-compatible socket:

• Copilot in Docker — real benchmark with gateway capture: 4 tool calls extracted into the HAR, ATIF generated, and a passing verdict on a criterion that explicitly requires captured tool-call evidence. The downloaded artifact printed exactly Hello Scope!, exit 0, and its report completed.
• Claude Code on the host, and in Docker — full coding → evaluation → artifact execution → report.
• Lifecycle — stop/restart preserves projects, runs and verdicts; shutdown left zero owned containers.

pnpm exec vitest run — 231 files / 2,859 tests passing.

docs/architecture/scope-server.md documents packaging, storage layout, agent setup and consent, capture semantics and the observed coverage.

Before review

• Not rebased — 58 commits behind main. Developed against b494da81, last validated 2026-09-12.
• Some of it may already be fixed upstream. Fix: portal Generate/Regenerate requests for Azure AI Foundry reasoning-model deployments #1379 (Foundry reasoning-model requests), Bootstrap pnpm via a registry-honoring fallback when corepack can't reach its metadata endpoint #1374 (corepack behind registry proxies) and Forward the host npm registry into docker image builds #1373 (host npm registry in image builds) solve problems this branch also works around; those parts should be dropped in favour of the upstream versions. feat(api): Implement authentication #1385 (API authentication) and Discover workers dynamically and present registry agent names #1381 (dynamic worker discovery) touch the same files.
• Scope of capture. Gateway capture is enabled for the Copilot Docker worker only. Claude Code's natively compiled CLI can't reach its API through the gateway in either runtime, which is why docker-compose.yml still pins that worker to DevProxy; finishing that migration is out of scope here. Host capture is therefore opt-in via SCOPE_HOST_CAPTURE=1.
• Native Copilot on the host is unproven. ACP initialises but session/new times out against a personal MCP server returning HTTP 403 with a malformed initialize response. Environmental, but no corrected host benchmark completed.
• Loopback only, macOS arm64 only. No new auth mechanism — existing local/development auth behaviour is unchanged, and this predates feat(api): Implement authentication #1385. Remote TCP and Windows named-pipe engines are unsupported.

[github-actions]

Test Results (Node.js 22)

test: Run #210

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3443	3443	0	0	0	0	0	1m6s

🎉 All tests passed!

Github Test Reporter