Runs & SSE

An agent run is one logical session of tool calls against krabs. Every call is persisted, signed, and streamable.

What is a run

A run is a sequence of tool calls sharing the same run_id. Runs scope audit, billing, replay, and live streaming. Two callers operating concurrently produce two independent runs even if they touch the same records.

A run is created implicitly when an agent connects to mcp.krabs.dev — the MCP session id becomes the run id. For CLI- or HTTP-driven workflows, runs are created explicitly.

Creating a run

krabs runs create --agent agent_drafts --name "Q3 outreach pass"

Output:

run_id:    run_01HG7Z4X9Q8M2N7P3R5T6V8W
agent:     agent_drafts
name:      Q3 outreach pass
created:   2026-05-16T14:22:08Z
status:    open

The run stays open until you close it, or it ages out after 24 hours of inactivity.

Attaching calls

Pass the run id as a header or environment variable. Every call that carries it is attached to that run.

# HTTP
curl https://api.krabs.dev/v1/contact.upsert \
  -H "Authorization: Bearer $KRABS_API_KEY" \
  -H "X-Krabs-Run: run_01HG7Z4X9Q8M2N7P3R5T6V8W" \
  -H "Content-Type: application/json" \
  -d '{ … }'

# CLI
export KRABS_RUN_ID=run_01HG7Z4X9Q8M2N7P3R5T6V8W
krabs contact upsert --email ada@lovelace.dev

Calls without a run id land on an ad-hoc run named default that resets daily.

Streaming via SSE

Subscribe to a run with GET /v1/runs/{run_id}/stream. The response is Server-Sent Events: one event: tool_call message per call as it lands.

curl -N https://api.krabs.dev/v1/runs/run_01HG7Z4X9Q8M2N7P3R5T6V8W/stream \
  -H "Authorization: Bearer $KRABS_API_KEY" \
  -H "Accept: text/event-stream"

Sample frame:

event: tool_call
data: {
  "ts": "2026-05-16T14:22:31.418Z",
  "op": "contact.upsert",
  "args": { "identity": { "kind": "email", "value": "ada@lovelace.dev" } },
  "result": { "id": "ct_01HG…", "created": true },
  "latency_ms": 42
}

Tail

krabs runs tail polls the dashboard firehose and formats the stream for terminals.

krabs runs tail --agent agent_drafts

Output:

14:22:31.418  contact.upsert       42ms   ✓
14:22:31.690  identity.attach      18ms   ✓
14:22:32.103  interaction.record   61ms   ✓
14:22:32.890  deal.create          77ms   ✓
14:22:33.504  task.assign          22ms   ✕  invalid_assignee

--follow stays attached; --since 5m backfills the last five minutes before live-tailing.

Audit as replay

Every run is an append-only log of typed tool calls and results. That log is replayable: feed it through krabs runs replay with --dry-run and krabs re-executes each call against current state, reporting what would happen if executed today.

krabs runs replay run_01HG7Z4X9Q8M2N7P3R5T6V8W --dry-run

Useful for: debugging an outreach pass that misbehaved, regression-testing an agent after a prompt change, simulating a backfill before running it. No writes happen until you drop --dry-run.