Automate with the Runtime API

Run one job from a script

codewhale exec "Reply with exactly: pong"
codewhale exec --auto "fix the failing test and run it again"
codewhale exec --auto --output-format stream-json "update the changelog"

Plain exec answers once without tools. --auto lets it use tools and approves them automatically, so use it only in a repository or container you trust; it never widens the sandbox. --output-format stream-json prints one JSON event per line and saves the session so --continue can pick it up. --max-turns and --allowed-tools put limits on a run.

Start the Runtime API

export CODEWHALE_RUNTIME_TOKEN="$(openssl rand -hex 32)"
codewhale app-server --http            # http://127.0.0.1:7878

Set the token yourself before starting; if you do not, Codewhale generates one for the process and does not print it. Every /v1/* request must send it as Authorization: Bearer <token>. --port changes the port.

Send a turn and watch it

API=http://127.0.0.1:7878
AUTH="Authorization: Bearer $CODEWHALE_RUNTIME_TOKEN"

THREAD=$(curl -s -X POST "$API/v1/threads" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{}' | jq -r .id)

curl -s -X POST "$API/v1/threads/$THREAD/turns" -H "$AUTH" \
  -H "Content-Type: application/json" -d '{"prompt": "Summarize README.md"}'

curl -N "$API/v1/threads/$THREAD/events?since_seq=0" -H "$AUTH"

A thread is a conversation; a turn is one request and everything Codewhale does for it. The events stream replays from the sequence number you give and then stays open for new events, so a client that reconnects misses nothing.

Stop a turn

POST /v1/threads/{id}/turns/{turn_id}/interrupt

Answer an approval

POST /v1/approvals/{approval_id}

Steer a running turn

POST /v1/threads/{id}/turns/{turn_id}/steer

List saved sessions

GET /v1/sessions

docs/RUNTIME_API.md lists every route, request body, and event.

Pick another connection

codewhale app-server --stdio

JSON-RPC over standard input and output, with no network listener. Good for an SDK or a local probe.

codewhale serve --acp

Agent Client Protocol for editors such as Zed.

codewhale serve --mcp

Offer Codewhale's tools to another MCP client. See Connect tools with MCP.

codewhale web

The built-in browser client, on the same API.

codewhale doctor --json

Health and capabilities as JSON, with no secrets.

Keep it private

• The server listens on 127.0.0.1 by default. The token is a local guard, not a replacement for TLS or a VPN; do not expose the port to a network.
• --insecure-no-auth is accepted only on a loopback address.
• The API never returns your provider keys. Health and capability reports carry only metadata — no secrets, file contents, or messages.

Next