# cmux platform API

> The private cmux cloud platform: derived cloud environments, the agent mesh, machines, inference,
> chat shares and more, as one HTTP API on Cloudflare Workers. Start with docs/agents.md (base URLs,
> auth, errors, a worked example), then read the operation you need in openapi.json.

Most surfaces are on in the development deployment only (https://cmux-platform-development.debussy.workers.dev);
staging and production answer `/v1/health` and `/v1/projects`. A surface that is off answers 404 `*.not_found`
on every path. Errors are JSON `{_tag, message}`, and most add a stable dotted `code` to branch on; an empty 400 means the request did not match the schema.

## Start here

- [Agent guide](docs/agents.md): base URLs, which token each route takes, the error format, conventions, a worked example
- [OpenAPI spec](openapi.json): every public operation, schema, example and error code (generated from src/api/)

## Surfaces (OpenAPI tags)

- Slack: `/v1/slack`, install the Chief bridge, read/disconnect your workspaces, and receive signed Slack events; development only ([setup](docs/slack-bridge.md))

- System: `GET /v1/health`, liveness and the deployed commit; no auth
- Projects: `/v1/projects`, an in-memory example resource; no auth; useful as a client smoke test
- Environments: `/v1/environments`, the environment a cloud chat runs in, derived from a repo and ref ([design](docs/github-connector-clone.md))
- Mesh: `/v1/mesh`, every acpmux daemon of a team reaches every other: sessions, messages, inbox
- Mesh node registry: `/v1/mesh/nodes`, WireGuard node registration and peer maps for machine credentials
- Mesh node ACL: `/v1/mesh/nodes/acl`, node-to-node denies set by team members
- Inference: `/v1/inference`, an OpenAI-compatible model router ([design](docs/inference-router.md))
- Chief: `/v1/chief`, the signed-in person's stable Chief address, scoped wire ticket and main-conversation messages; see docs/chief-web.md
- Chat shares: `/v1/chat-shares`, hosted rooms for sharing an agent chat with guests
- Cloud task results: `/v1/task-results`, publish a finished machine task as a branch, diff card and optional pull request
- Cloud triggers: `/v1/triggers`, register owner-scoped GitHub filters and read the exact Cloud chat delivery and reply
- Cloud trigger ingress: `/v1/triggers/{id}/github` accepts signed GitHub bytes; `/v1/triggers/{id}/authorize` verifies scoped guest trigger operations
- Vault env: `/v1/vault/env`, a person saves, lists and deletes their own env entries (API keys, provider credentials, variables; never a subscription login); development only
- Vault grants: `/v1/vault/grants`, a person lists, writes and revokes which of their machines read which entries, until when; development only
- Vault reads: `/v1/vault/reads`, a person lists the latest machine reads of their vault (entry names, never values) and the alerts they raised; development only
- Vault (machine): `/v1/vault/machine`, a machine its owner consented to (a granted joined machine, or their own Cloud machine) reads their env entries; development only
- Dependency caches: `/v1/dep-cache`, a Cloud machine restores its installed dependencies (node_modules, Cargo's registry, the npm, pnpm and uv caches) by lockfile key, and uploads them after a cold install, per person or team; development only
- Machines: `/v1/machines`, a team's machines and snapshots under the team machine policy ([design](docs/team-machines.md)); `/v1/cloud/machines/{machine}/previews/refresh` discovers private new Cloud port previews ([staging setup](docs/cloud-previews.md))
- Cloud environments: `/v1/cloud-environments`, what a Cloud chat's machine is set up with (setup script, variables, secrets, network access), per person or team, with a Default in each
- Workspace machines: `/v1/workspaces/{workspace}/machine`, a workspace's own small machine from a warm snapshot, one workspace per machine
- defaultMachines: `POST /v1/machines/default`, the account owner's private default Cloud machine, with a server-chosen workspace and key, normal caps and budget admission
- Cloud turn capabilities: `/v1/workspaces/{workspace}/machine/turns/{turn}/capability`, owner-issued preparation and execution authority for one turn and generation
- Cloud turn execution: `/v1/turn-execution/claim` and `/finish`, validate preparation or claim and finish execution with a scoped turn capability ([contract](docs/team-machines.md#10-whole-machine-turn-checkpoints))
- Machine automatic sizing: `/v1/machines/{id}/autosize`, a machine grows (snapshot first) when starved and shrinks after a long idle, on its own; this reads its decisions and why ([design](docs/machine-autosize.md))
- Cloud fork runs: `/v1/workspaces/{workspace}/fork-runs`, one durable source snapshot and N copy-on-write machines across harnesses, with one selected sync-back child
- Machine placement: `/v1/machines/pick` (old name `/v1/machines/place` still works), Auto placement of a new machine ([design](docs/machine-placement.md))
- machineReservations: `/v1/machines/reservations`, reserve a warm Cloud machine while composing, bind it when Send starts, or release it when abandoned
- Registered machines: `/v1/machines/joined/heartbeat` (old path `/v1/machines/registered/heartbeat` still works), capacity reports from cmux-owned hosts
- Machine join credentials: `/v1/machines/join-tokens`, `/v1/machines/credentials`, onboarding a machine ([recovery](docs/machine-join-recovery.md))
- Machine join redemption: `/v1/machines/join-tokens/redeem`, a machine's single-use join
- Connectors: `/v1/connectors`, repository connectors (GitHub, GitLab)
- Me: `/v1/me/github`, which GitHub account the caller's cmux account has connected (login, never a token)
- Artifacts: `/v1/artifacts`, versioned per-user artifacts and synced memory (off everywhere for now)
- Sync: `/v1/sync`, the per-user content-addressed blob store behind `cmux link sync push`: upload once, read back by token or one-hour `csg_` grant; development only
- Execution receipts: `/v1/execution-receipts`, redacted evidence of where work ran ([provenance](docs/execution-source-provenance.md)); off everywhere for now
- Hosted MCP (development only): `POST /mcp`, a Streamable HTTP MCP endpoint for GitHub reads and approved issue comments; `create_issue_comment` requires a verified `mcp:write` bearer ([design](docs/hosted-mcp.md))
- Authentication: `/v1/auth/challenge`, `/v1/auth/token`, install challenge and access-token minting
- JWKS: `/.well-known/jwks.json`, public keys for verifying install access tokens
- Hosted connector resources: `/v1/resources` is off in this deployment and returns 404 `resource.not_found` until a resolver is enabled; when enabled, it provides durable team-scoped references to provider resources
- Native network: `GET /v1/host/network/target`, server-selected Native routing metadata for an authenticated client install; development only

## Optional

- [README](README.md): how the service is built, tested and deployed
- [Chat turn execution contract](docs/chat-turn-execution-contract.md)
- [Credential boundaries](docs/credential-boundary-comparison.md)
- [VM-hours meter](docs/vm-hours-meter.md)