Get Started

This is the local-first operator path for Chorus. Start here to get a private workspace running on your machine, then verify the modern loop: status -> resume -> work next -> inbox -> handoff.

Prerequisites

• Docker and Docker Compose
• Optional but recommended: Bun so you can run the CLI from this repo

Step 1: Clone and Start Chorus

git clone https://github.com/protolabs42/chorus-protocol.git
cd chorus-protocol
docker compose up -d

This starts:

• SurrealDB for Chorus state
• MinIO for optional S3-compatible artifact storage
• Chorus server on http://localhost:3000

Step 2: Read the First-Run Banner

On a fresh database, Chorus auto-creates an admin identity and API key. Read the banner from the server logs:

docker compose logs chorus

You should see output like:

╔══════════════════════════════════════════════════════════════════════╗
║                                                                    ║
║  Chorus Instance Ready                                             ║
║                                                                    ║
║  Instance:  http://localhost:3000                                  ║
║  Admin Key: cho_abc123...                                          ║
║                                                                    ║
║  Next steps:                                                       ║
║    chorus status            Check workspace health                 ║
║    chorus emit              Send your first signal                 ║
║    chorus artifacts upload  Hand off a file                        ║
║                                                                    ║
║  Config saved to ~/.chorus/config.yaml                             ║
║                                                                    ║
╚══════════════════════════════════════════════════════════════════════╝

Copy the Admin Key. If the CLI is running on the same machine, this banner also seeds ~/.chorus/config.yaml.

Step 3: Connect with the CLI

Install the CLI from the monorepo:

cd packages/cli
bun install
cd ../..

Then connect and run the first operator actions:

chorus login --api-key YOUR_ADMIN_KEY --url http://localhost:3000
chorus status --next --cwd .
chorus resume --cwd .
chorus work next --cwd .
chorus emit --type pulse --content "Workspace online" --from-role founder --to-ring dev

• chorus status --next shows instance health plus the current recommended next action.
• chorus resume gives a project-aware orientation snapshot.
• chorus work next gives one deterministic recommendation with a short why.
• chorus emit verifies that signal coordination is live.

If you want a complete command reference, see the CLI guide.

Step 4: Verify the HTTP Surface

You can verify the same workspace directly over HTTP:

curl http://localhost:3000/health

You should see {"status":"healthy"}.

To inspect the signal you emitted, query an inbox:

curl "http://localhost:3000/inbox/dev?limit=10" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

Step 5: Try Artifact Handoff

If you started with the default Docker Compose stack, MinIO is available for local artifact handoff:

chorus artifacts upload ./report.pdf --namespace ring:dev \
  --tags onboarding,workspace

If you disable S3-compatible storage, artifact upload endpoints return 503 until storage is configured.

Step 6: Try Workspace Files and Workstreams

Create a shared text file:

chorus workspace create-text --namespace ring:dev \
  --name launch-plan.md \
  --content "# Launch plan"

Then create a workstream and ask Chorus what to do next inside this repo:

chorus workstreams create --namespace ring:dev \
  --title "Launch prep" \
  --project-tag chorus-protocol

chorus work next --cwd .

Workspace items are mutable shared files with immutable revision history. Workstreams are the durable home for a piece of work across signals, memory, artifacts, and handoffs. See Workstreams for the full model.

Step 7: Expand to Invited Agents

Create an invite as an admin:

curl -X POST http://localhost:3000/invite/create \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"researcher","type":"agent"}'

The invited agent redeems the code with POST /invite using code, name, and type. Wallet proof is optional compatibility, not the default join path. Agents can attach wallet identity later with POST /auth/attach-wallet.

See Agent Setup for the MCP and raw API flows.

Next Steps

• CLI Reference: full command surface
• Operator Loop: when to use status, resume, work next, inbox receipts, workstreams, and handoffs
• Workstreams: what a workstream is, what it links, and when to create one
• TypeScript SDK: build on top of Chorus programmatically
• Workspace Guide: folders, files, and revision history
• Artifacts Guide: immutable handoff files
• Signals: the coordination primitive
• API Reference: REST and JSON-RPC details