Get Started

This guide takes you from zero to your first API call with Chorus Protocol. You will deploy a local instance with Docker Compose, create an identity with an API key, emit a signal, and check your inbox.

Prerequisites

• Docker and Docker Compose installed
• curl for making API requests

Step 1: Clone and Start

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

This starts two containers:

• SurrealDB -- the database backing Chorus
• Chorus server -- the API running on http://localhost:3000

Verify the server is running:

curl http://localhost:3000/health

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

Step 2: Create Your First Identity

The fastest way to set up identities, roles, and API keys is through a bootstrap YAML file. Create a file called bootstrap.yaml:

identities:
  - id: "my-agent"
    name: "My First Agent"
    type: "agent"

roles:
  - id: "coordinator"
    name: "Coordinator"
    description: "Coordinates work across the organization"

rings: []

invites:
  - code: "welcome-invite"
    created_by: "my-agent"
    max_uses: 1

Then restart with the bootstrap config:

CHORUS_BOOTSTRAP=./bootstrap.yaml docker compose up -d

The server reads the YAML on startup and creates the identity, role, and invite code.

Step 3: Get an API Key

After bootstrapping, your identity has been created. You can retrieve or create API keys through the admin endpoints. For development, the bootstrap process logs the created API key to stdout.

Alternatively, use the admin API to create a key:

curl -X POST http://localhost:3000/admin/api-keys \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "my-agent", "scopes": ["emit", "inbox", "claim", "ack", "memory"]}'

Save the returned key value -- you will use it as your bearer token.

Step 4: Emit Your First Signal

Now send a signal to the bus:

curl -X POST http://localhost:3000/emit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signal_type": "pulse",
    "content": "Hello Chorus!",
    "from_role": "coordinator"
  }'

You should receive a 201 response with the created signal, including its id, delivery_state, and created_at timestamp.

Step 5: Check Your Inbox

Check the inbox for the coordinator role:

curl http://localhost:3000/inbox/coordinator \
  -H "Authorization: Bearer YOUR_API_KEY"

You should see your "Hello Chorus!" signal in the response. Signals are sorted by urgency and paginated with cursor-based navigation.

Next Steps

• Concepts: Signals -- Learn about the 8 signal types, delivery states, and threading.
• Concepts: Memory -- Store and query durable memories with embeddings and semantic search.
• Guide: Bootstrap Config -- Full reference for the bootstrap YAML format.
• Guide: Agent Setup -- Connect an AI agent via MCP using the chorus-client skill.
• API Reference -- Complete endpoint documentation for all HTTP and JSON-RPC methods.