ReleaseLatest release v0.10.2 · 24 Eki 2026These pages describe v0.10.2, the published release.Changelog →

Automate with the Runtime API

Use codewhale exec for a one-shot job, or follow this tutorial to create a thread and stream a turn through the local Runtime API. The complete reference, generated from the repository's main branch, covers routes, request fields, events and compatibility limits.

Run one job from a script

Terminal

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

Plain exec answers once without tools. By default, --auto enables Full Access: tools run without asking, shell commands have no Codewhale sandbox, and trust mode lets file tools write outside the workspace. Any --sandbox other than danger-full-access (or the equivalent sandbox_mode in config) keeps trust mode off. Add --sandbox workspace-write for the shell sandbox, where available, and file-tool workspace restrictions; external-sandbox relies on your own isolation. Put flags before the prompt, and use -- before prompt text that starts with - or contains literal exec flags. Runs that offer tools are saved in every output format. --output-format stream-json prints one JSON event per line and also saves answer-only runs so --continue can pick them up. --max-turns and --allowed-tools put limits on a run.

Start the Runtime API

Use a POSIX shell with curl, jq and openssl, and a Codewhale build that supports app-server --http. Run all steps in the same terminal so the token, server process id and thread id remain available.

Note: The commands on this page exist in the published release; check codewhale --version before comparing behavior. Connecting a provider is required for the turn below, and that request uses your provider's normal billing; starting the server and checking /health do not send a model request.

Terminal

export CODEWHALE_RUNTIME_TOKEN="$(openssl rand -hex 32)"
codewhale app-server --http &
CODEWHALE_RUNTIME_PID=$!
curl --fail --silent --show-error --retry 10 --retry-connrefused   --retry-delay 1 http://127.0.0.1:7878/health

The health command must return successfully before you continue; inspect the server output if it fails or the port is occupied. Keep the generated token private and send it as Authorization: Bearer <token> on every /v1/* request.

Send a turn and watch it

Terminal

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

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

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

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

Check that thread creation returns a nonempty id and the turn request returns an accepted turn; the events stream should then show the turn and its recorded result. Keep the last accepted seq for reconnects, handle the terminal stream.end frame, and follow the replay contract instead of assuming every disconnect is recoverable.

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

The Runtime API reference renders the contract from the repository's main branch, including endpoint tables, request fields, event envelopes and version limits.

Stop the tutorial server

Press Ctrl+C to close the event stream, then stop the server you started in this terminal. Closing the stream alone does not stop the server or interrupt an active model turn; use the interrupt endpoint above if needed.

Terminal

kill "$CODEWHALE_RUNTIME_PID"
unset CODEWHALE_RUNTIME_TOKEN CODEWHALE_RUNTIME_PID

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

Read the Runtime API reference

Find exact routes, fields, event schemas and compatibility behavior.

Open the browser client

A ready-made client for the same API.

Run commands on events

React to session events without writing a client.

Run a workflow

Durable, multi-step runs you can check from any terminal.