Getting Started

Get Koor running and make your first API call in under 5 minutes.

Install

Pre-built Binaries

Download from the Releases page. Binaries are available for:

Build from Source

Requires Go 1.21 or later.

git clone https://github.com/DavidRHerbert/koor.git
cd koor
go build ./cmd/koor-server
go build ./cmd/koor-cli

Both binaries are self-contained with zero external runtime dependencies. The dashboard is embedded in the server binary via go:embed.

Start the Server

./koor-server

Output:

time=2026-02-09T14:00:00.000Z level=INFO msg="koor server starting" api=localhost:9800 dashboard=localhost:9847 data_dir=. auth=false

The server is now listening on two ports:

Data is stored in ./data.db (SQLite, WAL mode).

First Commands

Using curl

Set a state value:

curl -X PUT http://localhost:9800/api/state/api-contract \
  -H "Content-Type: application/json" \
  -d '{"version":"1.0","endpoints":["/api/users","/api/orders"]}'

Response:

{"key":"api-contract","version":1,"hash":"a1b2c3...","content_type":"application/json","updated_at":"2026-02-09T14:00:01Z"}

Get it back:

curl http://localhost:9800/api/state/api-contract

Response:

{"version":"1.0","endpoints":["/api/users","/api/orders"]}

List all keys:

curl http://localhost:9800/api/state

Check health:

curl http://localhost:9800/health

Using koor-cli

Configure the CLI (one-time):

./koor-cli config set server http://localhost:9800

Then use it:

# Set state
./koor-cli state set api-contract --data '{"version":"1.0","endpoints":["/api/users"]}'

# Get state
./koor-cli state get api-contract

# List keys
./koor-cli state list

# Check health
./koor-cli status

# Pretty-print any output
./koor-cli state list --pretty

Enable Authentication

Start the server with a token:

./koor-server --auth-token secret123

With curl, add the Authorization header:

curl -H "Authorization: Bearer secret123" http://localhost:9800/api/state

With koor-cli, set the token:

./koor-cli config set token secret123
./koor-cli state list

The /health endpoint never requires authentication.

Publish and Subscribe to Events

Publish an event:

curl -X POST http://localhost:9800/api/events/publish \
  -H "Content-Type: application/json" \
  -d '{"topic":"api.change.contract","data":{"version":"2.0"}}'

View recent events:

curl "http://localhost:9800/api/events/history?last=10"

Subscribe to events in real-time (requires a WebSocket client):

websocat ws://localhost:9800/api/events/subscribe?pattern=api.*

Or use the CLI polling fallback:

./koor-cli events subscribe "api.*"

Register an Agent Instance

./koor-cli register claude-frontend --workspace /projects/frontend --intent "building login page"

Save the returned token and id — the token is only shown on registration.

List all registered instances:

./koor-cli instances list --pretty

Open the Dashboard

Navigate to http://localhost:9847 in a browser. The dashboard shows live state, events, instances, and server metrics.

Next Steps