{"_id":"@aywengo/mercury","_rev":"5-a4806057149e453651f10507fbc489e2","name":"@aywengo/mercury","dist-tags":{"rc":"0.1.0-rc2","latest":"0.2.0"},"versions":{"0.1.0-rc1":{"name":"@aywengo/mercury","version":"0.1.0-rc1","license":"MIT","_id":"@aywengo/mercury@0.1.0-rc1","maintainers":[{"name":"aywengo","email":"aywengo@gmail.com"}],"bin":{"mercury":"dist/src/cli.js","mercuryctl":"dist/client/bin.js"},"dist":{"shasum":"17d91a730a0c827db42a69ccca77b969c0ad4f53","tarball":"https://registry.npmjs.org/@aywengo/mercury/-/mercury-0.1.0-rc1.tgz","fileCount":185,"integrity":"sha512-x0CuR+kKZXnLGWJq6vnrHSjPh+r042262b9m+nEqLh2KDQweO3Ld5c1pwsRzzW1KgyzWTFXk7UrK1gw1Uo39QQ==","signatures":[{"sig":"MEYCIQC51/cWkPvEQrdwgIq94Fe1beUyttmuGoLjWAIBOpRzyQIhAO7P1UIvnJdHoYAx2joUjW7orbBMRn0bb6Xw1VZuncil","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1483276},"type":"module","engines":{"node":">=22.18.0"},"gitHead":"961abb784d519199e5d5b744e763854064741df7","private":false,"scripts":{"gc":"node src/cli.ts gc","dev":"node src/cli.ts dev","test":"npm run test:core && npm run test:fleet && npm run test:client","fleet":"node fleet/cli.ts","server":"node src/cli.ts server","worker":"node src/cli.ts worker","migrate":"node src/cli.ts migrate","prepare":"npm run build:client && npm run build:server","test:core":"node --test --test-timeout=180000 'test/*.test.ts'","typecheck":"tsc --noEmit","test:fleet":"node --test --test-timeout=180000 'fleet/test/*.test.ts'","test:client":"node --test --test-timeout=180000 'client/test/*.test.ts'","build:client":"tsc -p tsconfig.client.json","build:server":"tsc -p tsconfig.server.json"},"_npmUser":{"name":"aywengo","email":"aywengo@gmail.com"},"_npmVersion":"11.19.0","description":"Durable long-running coding orchestration for PrimeAgent and other agent backends","directories":{},"_nodeVersion":"26.7.0","dependencies":{"express":"^4.21.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^24.0.0","@types/express":"^4.17.21"},"_npmOperationalInternal":{"tmp":"tmp/mercury_0.1.0-rc1_1788765108101_0.7053632430057071","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-rc2":{"name":"@aywengo/mercury","version":"0.1.0-rc2","keywords":["orchestration","coding-agent","primeagent","long-running-jobs","cli"],"author":{"name":"Roman Melnyk"},"license":"MIT","_id":"@aywengo/mercury@0.1.0-rc2","maintainers":[{"name":"aywengo","email":"aywengo@gmail.com"}],"homepage":"https://github.com/aywengo/mercury#readme","bugs":{"url":"https://github.com/aywengo/mercury/issues"},"bin":{"mercury":"dist/src/cli.js","mercuryctl":"dist/client/bin.js"},"dist":{"shasum":"b6e3450c7b8ccbf3b11fb780feed00c71b999d3a","tarball":"https://registry.npmjs.org/@aywengo/mercury/-/mercury-0.1.0-rc2.tgz","fileCount":183,"integrity":"sha512-ZWDcErDygWSXJYsf4gVNJZD6IWCAHx0sI9XfsS9JZPyjI4IRihDgw7Jm5nMEre3KKI5pBwV0bodKIRvMAcdXBw==","signatures":[{"sig":"MEUCIGaU81rK4AIKrvGRUT9oMbF5Bd8r3SZg6me9ct/9CSazAiEAiChOqPPc/qSTpBqrDIh5PwifQtexz2koQLpyN56DJ4g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aywengo%2fmercury@0.1.0-rc2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1488141},"type":"module","engines":{"node":">=22.18.0"},"gitHead":"aab0e9b3750c22746b0561d6311a74d7669a2ca0","private":false,"scripts":{"gc":"node src/cli.ts gc","dev":"node src/cli.ts dev","test":"npm run test:core && npm run test:fleet && npm run test:client","fleet":"node fleet/cli.ts","prepr":"node e2e/prepr.ts","server":"node src/cli.ts server","worker":"node src/cli.ts worker","migrate":"node src/cli.ts migrate","prepare":"npm run build:client && npm run build:server","test:e2e":"node --test --test-timeout=900000 'e2e/*.test.ts'","test:core":"node --test --test-timeout=180000 'test/*.test.ts'","typecheck":"tsc --noEmit","test:fleet":"node --test --test-timeout=180000 'fleet/test/*.test.ts'","test:client":"node --test --test-timeout=180000 'client/test/*.test.ts'","build:client":"tsc -p tsconfig.client.json","build:server":"tsc -p tsconfig.server.json","test:e2e:config":"docker compose -f e2e/compose.yml config --quiet"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","approver":{"name":"aywengo","email":"aywengo@gmail.com"},"trustedPublisher":{"id":"github","oidcConfigId":"oidc:607a296a-4c61-4931-a898-b6395e437907"}},"repository":{"url":"git+https://github.com/aywengo/mercury.git","type":"git"},"_npmVersion":"11.19.0","description":"Durable long-running coding orchestration for PrimeAgent and other agent backends","directories":{},"_nodeVersion":"24.20.0","dependencies":{"express":"^4.21.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"typescript":"^5.8.3","@types/node":"^24.0.0","@types/express":"^4.17.21","testcontainers":"^12.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mercury_0.1.0-rc2_1788899852023_0.6861495156476383","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@aywengo/mercury","version":"0.1.0","keywords":["orchestration","coding-agent","primeagent","long-running-jobs","cli"],"author":{"name":"Roman Melnyk"},"license":"MIT","_id":"@aywengo/mercury@0.1.0","maintainers":[{"name":"aywengo","email":"aywengo@gmail.com"}],"homepage":"https://github.com/aywengo/mercury#readme","bugs":{"url":"https://github.com/aywengo/mercury/issues"},"bin":{"mercury":"dist/src/cli.js","mercuryctl":"dist/client/bin.js"},"dist":{"shasum":"163923050c54f198128db9851db547f5881bf079","tarball":"https://registry.npmjs.org/@aywengo/mercury/-/mercury-0.1.0.tgz","fileCount":183,"integrity":"sha512-KynHF70/7B/hKi7Qrx84n/akzGY81xD40vxewtCYwzrSk0mx7EH6BbCSU0rAUkhSe2cXZV3dA5cc71eFRoFR3A==","signatures":[{"sig":"MEQCIDQfKIYDVDXrUo7oZseHtqCFrrB7TiOBSqYERHJjFR8rAiARfvH1xrwgdJX3GvJKIesdzTvt2ecaYGXomm/CfQbnJw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aywengo%2fmercury@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1488129},"type":"module","engines":{"node":">=22.18.0"},"gitHead":"808224dab98e0ec9c82b1687fd0c1f9cd04705e8","private":false,"scripts":{"gc":"node src/cli.ts gc","dev":"node src/cli.ts dev","test":"npm run test:core && npm run test:fleet && npm run test:client","fleet":"node fleet/cli.ts","prepr":"node e2e/prepr.ts","server":"node src/cli.ts server","worker":"node src/cli.ts worker","migrate":"node src/cli.ts migrate","prepare":"npm run build:client && npm run build:server","test:e2e":"node --test --test-timeout=900000 'e2e/*.test.ts'","test:core":"node --test --test-timeout=180000 'test/*.test.ts'","typecheck":"tsc --noEmit","test:fleet":"node --test --test-timeout=180000 'fleet/test/*.test.ts'","test:client":"node --test --test-timeout=180000 'client/test/*.test.ts'","build:client":"tsc -p tsconfig.client.json","build:server":"tsc -p tsconfig.server.json","test:e2e:config":"docker compose -f e2e/compose.yml config --quiet"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","approver":{"name":"aywengo","email":"aywengo@gmail.com"},"trustedPublisher":{"id":"github","oidcConfigId":"oidc:607a296a-4c61-4931-a898-b6395e437907"}},"repository":{"url":"git+https://github.com/aywengo/mercury.git","type":"git"},"_npmVersion":"11.19.0","description":"Durable long-running coding orchestration for PrimeAgent and other agent backends","directories":{},"_nodeVersion":"24.20.0","dependencies":{"express":"^4.21.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^24.0.0","@types/express":"^4.17.21","testcontainers":"^12.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mercury_0.1.0_1788932988402_0.7969805234326364","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aywengo/mercury","version":"0.1.1","keywords":["orchestration","coding-agent","primeagent","long-running-jobs","cli"],"author":{"name":"Roman Melnyk"},"license":"MIT","_id":"@aywengo/mercury@0.1.1","maintainers":[{"name":"aywengo","email":"aywengo@gmail.com"}],"homepage":"https://github.com/aywengo/mercury#readme","bugs":{"url":"https://github.com/aywengo/mercury/issues"},"bin":{"mercury":"dist/src/cli.js","mercuryctl":"dist/client/bin.js"},"dist":{"shasum":"9254607cf51a3354167ff9c183020a2272b967ec","tarball":"https://registry.npmjs.org/@aywengo/mercury/-/mercury-0.1.1.tgz","fileCount":185,"integrity":"sha512-0SMBCjvP1dVyuPu8QSgr7z3nC3cuwH/mY57KgSOpGH/wBtuHIeQPJ8/Lp2cCN7WztGfb1UlwmtMJu9lvhMm7rA==","signatures":[{"sig":"MEQCIAEAJruhgpgnePTmEPp735ZB549x45CjmWXw1NyA/O+KAiBSxkFbAQOeL4Ulw1KpvvTqy6Lbz8BaQo/uLvBOyuPv2g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aywengo%2fmercury@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":1492376},"type":"module","engines":{"node":">=22.18.0"},"gitHead":"0796f3b1c1283c97fcbdf0bb360a7e1cb7fadb0d","private":false,"scripts":{"gc":"node src/cli.ts gc","dev":"node src/cli.ts dev","test":"npm run test:core && npm run test:fleet && npm run test:client","fleet":"node fleet/cli.ts","prepr":"node e2e/prepr.ts","server":"node src/cli.ts server","worker":"node src/cli.ts worker","migrate":"node src/cli.ts migrate","prepare":"npm run build:client && npm run build:server","test:e2e":"node --test --test-timeout=900000 'e2e/*.test.ts'","test:core":"node --test --test-timeout=180000 'test/*.test.ts'","typecheck":"tsc --noEmit","test:fleet":"node --test --test-timeout=180000 'fleet/test/*.test.ts'","build:fleet":"tsc -p tsconfig.fleet.json","test:client":"node --test --test-timeout=180000 'client/test/*.test.ts'","build:client":"tsc -p tsconfig.client.json","build:server":"tsc -p tsconfig.server.json","test:e2e:config":"docker compose -f e2e/compose.yml config --quiet"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","approver":{"name":"aywengo","email":"aywengo@gmail.com"},"trustedPublisher":{"id":"github","oidcConfigId":"oidc:607a296a-4c61-4931-a898-b6395e437907"}},"repository":{"url":"git+https://github.com/aywengo/mercury.git","type":"git"},"_npmVersion":"11.19.0","description":"Durable long-running coding orchestration for PrimeAgent and other agent backends","directories":{},"_nodeVersion":"24.20.0","dependencies":{"express":"^4.21.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^24.0.0","@types/express":"^4.17.21","testcontainers":"^12.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mercury_0.1.1_1789110342101_0.31200259590313695","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"@aywengo/mercury@0.2.0","bin":{"mercury":"dist/src/cli.js","mercuryctl":"dist/client/bin.js"},"bugs":{"url":"https://github.com/aywengo/mercury/issues"},"dist":{"shasum":"28952ccd74dabe4d8a9d65014544588ec35b465f","tarball":"https://registry.npmjs.org/@aywengo/mercury/-/mercury-0.2.0.tgz","integrity":"sha512-saWW4sYVyhBeZSk2y6hvfOP7uYkQoCd+ChyfrPhW0IlfnBmTo2tuHMPVaRI/XU17SWeRSNH5GpIFWjbjWHpWtg==","fileCount":301,"unpackedSize":3091587,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aywengo%2fmercury@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDfVReSj2l3FLruRDIkndevaWiQd8OTFCEa15gDlBNlhgIhAMiOSVmdS1MRlanevZfqTb+ofSBj2uN37rt57HBJEcKs"}]},"name":"@aywengo/mercury","type":"module","author":{"name":"Roman Melnyk"},"engines":{"node":">=22.18.0"},"gitHead":"e1f9ba5373cb4b43c398442863b96f26e509b701","license":"MIT","private":false,"scripts":{"gc":"node src/cli.ts gc","dev":"node src/cli.ts dev","test":"npm run test:core && npm run test:fleet && npm run test:atlas && npm run test:client","atlas":"node atlas/cli.ts","fleet":"node fleet/cli.ts","prepr":"node e2e/prepr.ts","server":"node src/cli.ts server","worker":"node src/cli.ts worker","migrate":"node src/cli.ts migrate","prepare":"npm run build:client && npm run build:server","test:e2e":"node --test --test-timeout=900000 'e2e/*.test.ts'","test:core":"node --test --test-timeout=180000 'test/*.test.ts'","typecheck":"tsc --noEmit","test:atlas":"node --test --test-timeout=180000 'atlas/test/*.test.ts'","test:fleet":"node --test --test-timeout=180000 'fleet/test/*.test.ts'","build:atlas":"tsc -p tsconfig.atlas.json","build:fleet":"tsc -p tsconfig.fleet.json","test:client":"node --test --test-timeout=180000 'client/test/*.test.ts'","build:client":"tsc -p tsconfig.client.json","build:server":"tsc -p tsconfig.server.json","test:install":"bats test/install.bats","test:e2e:config":"docker compose -f e2e/compose.yml config --quiet"},"version":"0.2.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:607a296a-4c61-4931-a898-b6395e437907"},"approver":{"name":"aywengo","email":"aywengo@gmail.com"}},"homepage":"https://github.com/aywengo/mercury#readme","keywords":["orchestration","coding-agent","primeagent","long-running-jobs","cli"],"repository":{"url":"git+https://github.com/aywengo/mercury.git","type":"git"},"_npmVersion":"11.19.0","description":"Durable long-running coding orchestration for PrimeAgent and other agent backends","directories":{},"maintainers":[{"name":"aywengo","email":"aywengo@gmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"express":"^4.21.2"},"publishConfig":{"access":"public"},"devDependencies":{"typescript":"^5.8.3","@types/node":"^24.0.0","@types/express":"^4.17.21","testcontainers":"^12.1.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mercury_0.2.0_1790505125338_0.453239350044764"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T07:11:47.804Z","modified":"2026-09-27T10:32:05.733Z","0.1.0-rc1":"2026-09-07T07:11:48.265Z","0.1.0-rc2":"2026-09-08T20:37:32.128Z","0.1.0":"2026-09-09T05:49:48.509Z","0.1.1":"2026-09-11T07:05:42.229Z","0.2.0":"2026-09-27T10:32:05.473Z"},"bugs":{"url":"https://github.com/aywengo/mercury/issues"},"author":{"name":"Roman Melnyk"},"license":"MIT","homepage":"https://github.com/aywengo/mercury#readme","keywords":["orchestration","coding-agent","primeagent","long-running-jobs","cli"],"repository":{"url":"git+https://github.com/aywengo/mercury.git","type":"git"},"description":"Durable long-running coding orchestration for PrimeAgent and other agent backends","maintainers":[{"name":"aywengo","email":"aywengo@gmail.com"}],"readme":"# Mercury\n\n<p align=\"center\">\n  <img src=\"docs/assets/mercury-hero.png\" width=\"800\" alt=\"Mercury: a harness for harnesses. Mercury orchestrates; agents like PrimeAgent, Claude Code, Hermes and Codex write the code.\">\n</p>\n\nMercury is a durable control plane for long-running coding agents, managing\nruns, state, workspaces, events, retries, and human input independently of\nbrowser sessions. Agents execute the coding work, while Mercury safely\norchestrates when, where, and with which tools and instructions they run.\n\nIt is a harness for harnesses. Mercury never inspects a repository, edits a\nfile, or runs a test; every one of those decisions belongs to the agent backend.\nWhat Mercury owns is everything that has to survive the agent process: the Run's\nidentity and state, its workspace, its event history, the queue and lease that\ndecide when it runs, and the human-input loop that resumes it. That separation is\nwhy one control plane can drive PrimeAgent, Claude, Hermes, a local CLI, a remote\nAPI, or a fake adapter in tests without any of them knowing about the others.\n\nMercury is a working Node.js and SQLite implementation. Creating a Run without\nan `agent` field uses the built-in `fake` adapter (no extra CLI). PrimeAgent,\nHermes, Claude, and declarative local/RPC/remote adapters are optional backends\nbehind `AgentAdapter`.\n\n## What Mercury provides\n\n- durable Runs whose lifetime is independent of HTTP, SSE and browser sessions;\n- a separate API process and background worker;\n- SQLite-backed scheduling, leases, state and event history;\n- isolated Git worktrees and optional container sandboxing;\n- structured progress events with resumable SSE;\n- cancellation, retry and human-input flows;\n- deterministic skill selection and per-Run skill records;\n- a static operations dashboard;\n- declarative local, remote and RPC agent adapters.\n\n## Control plane\n\n```mermaid\nflowchart TD\n    User[User] --> Surfaces[\"API, dashboard and chat\"]\n\n    subgraph controlPlane [Mercury control plane]\n        Surfaces --> RunService[RunService]\n        RunService --> RunStore[\"Run state and snapshots\"]\n        RunService --> Queue[\"Durable queue and leases\"]\n        RunService --> EventStore[\"Structured event store\"]\n    end\n\n    Queue --> Worker[Worker]\n\n    subgraph executionHarness [Execution harness]\n        Worker --> Workspace[\"Isolated workspace\"]\n        Worker --> Skills[\"Selected skills\"]\n        Worker --> Sandbox[\"Optional sandbox\"]\n        Worker --> Adapter[AgentAdapter]\n    end\n\n    subgraph agentBackends [Agent backends]\n        PrimeAgent[PrimeAgent]\n        Hermes[Hermes]\n        Claude[Claude]\n        LocalAgent[\"Local CLI agents\"]\n        RpcAgent[\"RPC agents\"]\n        RemoteAgent[\"Remote API agents\"]\n        FakeAgent[\"Fake agent for tests\"]\n    end\n\n    Adapter --> PrimeAgent\n    Adapter --> Hermes\n    Adapter --> Claude\n    Adapter --> LocalAgent\n    Adapter --> RpcAgent\n    Adapter --> RemoteAgent\n    Adapter --> FakeAgent\n    Adapter --> Translation[\"Event translation\"]\n    Translation --> EventStore\n    EventStore --> Surfaces\n```\n\nMercury controls orchestration and process lifetime. Agent backends retain\nresponsibility for inspecting repositories, editing code, running tools and\nproducing results. Backends other than `fake` need their CLI (or remote API)\ninstalled separately; `npm install` does not ship them.\n\n## Install\n\nRequires Node.js ≥ 22.18 (built-in `node:sqlite` and TypeScript type stripping).\nWhat each channel ships and how it is built:\n[`docs/distribution.md`](docs/distribution.md).\n\n**On a fresh machine — the host installer.** The guided path for macOS/Linux:\ndownload, inspect, run. It installs the pinned package into your user npm prefix\n(no sudo) and hands off to `mercury host setup`:\n\n```bash\ncurl -fsSL https://github.com/aywengo/mercury/releases/latest/download/install.sh | bash\n# or: npx @aywengo/mercury host install\n```\n\nThe `install.sh` asset ships with the next host release (0.1.0/0.1.1 predate\nthe installer and carry no asset), so the one-liner resolves from then on. Full\nwalkthrough and the `curl | bash` safety note:\n[`docs/host-installer.md`](docs/host-installer.md).\n\n**From a checkout — works today.** This also installs both commands, `mercury` (the\nhost) and `mercuryctl` (the operator client), because they ship in one package:\n\n```bash\ngit clone https://github.com/aywengo/mercury.git\ncd mercury\nnpm ci\nnpm install -g .\nmercury --version\n```\n\n`npm ci` compiles `dist/` as part of installing, so the binaries work immediately.\nInstalling with `npm install <git-url>` instead of a clone also works.\n\n**From npm and Homebrew.** These serve the published artifacts; see\n[Releases](https://github.com/aywengo/mercury/releases) for what is currently\navailable. Prereleases are published under a matching dist-tag, so ask for one explicitly with\n`@aywengo/mercury@rc`:\n\n```bash\nnpm install -g @aywengo/mercury@rc\nbrew tap aywengo/mercury https://github.com/aywengo/mercury\nbrew install mercury-ai                  # not `mercury`: that is a different project\n```\n\n`latest` is the stable channel and `@rc` is the prerelease channel. Both are moving dist-tags rather\nthan fixed versions: `npm install -g @aywengo/mercury` follows stable, and adding `@rc` follows release\ncandidates. Ask for an exact version with `@aywengo/mercury@0.1.0` if you need one to stay put.\n\nOne historical wrinkle worth knowing: `0.1.0-rc1` was published by hand without `--tag`, so npm applied\n`latest` to a prerelease and refuses to delete the tag (`400 Bad Request`). Publishing `0.1.0` moved\n`latest` onto a real version, which is the only correction npm allows. See issue #368.\n\nThere is no CLI-only channel. `mercuryctl` is inside the host package, so any install\nthat provides one provides the other.\n\n## Quick start\n\nFor prerequisites and a complete first-run walkthrough, see\n[`QUICKSTART.md`](QUICKSTART.md). The commands below run Mercury from a source\ncheckout without installing it.\n\n```bash\nnpm install\nMERCURY_EMBEDDED_WORKER=true \\\n  MERCURY_API_TOKENS=\"tok-alice:alice\" \\\n  npm run dev\n```\n\nThe dashboard is available at `http://127.0.0.1:3000/`. Sign in with `tok-alice`\n(the token, left of the colon — not the owner id `alice`). A first Run can omit\n`agent` and will use `fake`.\n\n## Commands\n\n| Command | Purpose |\n| --- | --- |\n| `npm run dev` | Start the API and, when enabled, the embedded development worker |\n| `npm run server` | Start the API only |\n| `npm run worker` | Start the background worker only |\n| `npm run migrate` | Apply database migrations (also applied automatically on start) |\n| `npm run gc` | Run one workspace-retention and quota pass |\n| `npm run typecheck` | Run TypeScript checks |\n| `npm test` | Run the core and Fleet test suites |\n| `npm run fleet` | Manage federated Mercury hosts |\n\n## Operating Runs from a terminal\n\n`mercuryctl` is the remote operator client: it talks to a running Mercury over its\nHTTP API and never starts a server or a worker.\n\n```bash\nexport MERCURY_CLIENT_URL=https://mercury.example.com:3000\nexport MERCURY_CLIENT_TOKEN=\"$MY_TOKEN\"     # never a flag: argv is readable with ps\n\nnpx mercuryctl agents list\nnpx mercuryctl runs create --task \"fix the flaky test\" --repo https://github.com/acme/api.git\nnpx mercuryctl runs list --status running --json | jq -r '.runs[].id'\nnpx mercuryctl runs watch \"$RUN_ID\"\n```\n\n`--json` emits exactly one machine-readable value on stdout, exit codes are stable\nand documented, and `mercuryctl --help` lists the commands this build implements.\nThe design is in [`docs/cli-tui-design.md`](docs/cli-tui-design.md).\n\n## Fleet\n\n[`fleet/`](fleet/) is a separate product in this repository: a federation layer\nthat runs several independent Mercury instances as one fleet. It talks to each\nMercury over its public HTTP API, never touches a Mercury database, and imports\nno Mercury code — a coupling test enforces the boundary.\n\nThe `fleet` CLI manages the host registry and probes it. `fleet serve` is the\npart that has to outlive the operator who started it: submitting and routing Runs\nacross hosts, reconciling their state after a crash, aggregating events, and\nserving one Prometheus rollup.\n\n```bash\nnpm run fleet -- hosts add mac-studio --url https://studio.lan:3000 --credential mac-studio\nnpm run fleet -- hosts list --live\nFLEET_API_TOKENS=\"tok-admin:admin\" npm run fleet -- serve\n```\n\nFleet has its own tests (`npm run test:fleet`), configuration, changelog, and\n[operator documentation](fleet/README.md). Its design is in\n[`docs/fleet-design.md`](docs/fleet-design.md).\n\n## Documentation\n\nStart with the [`documentation index`](docs/README.md), or go directly to:\n\n- [`System overview`](docs/overview.md)\n- [`API and dashboard`](docs/api.md)\n- [`Configuration`](docs/configuration.md)\n- [`Agent backends`](docs/agents.md)\n- [`Operations`](docs/operations.md)\n- [`Testing`](docs/testing.md)\n- [`Current status and limitations`](docs/status.md)\n- [`Deployment`](deploy/README.md)\n- [`Architecture specification`](ARCHITECTURE.md)\n- [`Crew design`](docs/crew/README.md)\n- [`Fleet design`](docs/fleet-design.md)\n\n## Current constraints\n\nMercury is intentionally single-host because its coordination store is SQLite.\nPrimeAgent RPC is the supported coding-agent transport; create-Run omits `agent`\nas `fake` unless `MERCURY_DEFAULT_AGENT` is set. Daemon mode is experimental and\nnot production-ready. Named network destinations are not currently enforced, and\nstored skill snapshots are not yet the bytes materialized by the worker.\n\nSee [`docs/status.md`](docs/status.md) for the complete and current limitations.\n\n## License and contributing\n\nMercury is [MIT](LICENSE) licensed. Host changes are recorded in\n[`CHANGELOG.md`](CHANGELOG.md); Fleet has [`fleet/CHANGELOG.md`](fleet/CHANGELOG.md).\nHow to cut a release: [`docs/releasing.md`](docs/releasing.md).\n\n- [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- [`SECURITY.md`](SECURITY.md)\n- [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)\n","readmeFilename":"README.md"}