Runtime API

codewhale app-server is the canonical local runtime API and control plane. Local SDKs, mobile/remote-control clients, and editor integrations talk to it instead of screen-scraping terminal output. The engine runs as a local-only process: every API binds to localhost by default — no hosted relay, no provider-token custody, no secret leakage. codewhale serve --http / --mobile remain compatibility aliases for app-server --http / --mobile and launch the identical server; new integrations should target app-server.

codewhale app-server --http

The full /v1/* HTTP/SSE runtime API (canonical entry), default 127.0.0.1:7878.

codewhale app-server --mobile

The runtime API plus the /mobile phone control page.

codewhale app-server --stdio

Newline-delimited JSON-RPC 2.0 control transport with no listener, for local SDKs and probes.

codewhale web [--port 7878]

The loopback-only browser client, embedded in the binary and opened in the default browser.

codewhale doctor --json

Machine-readable health and capability report.

codewhale serve --acp

ACP (Agent Client Protocol) stdio adapter for editors such as Zed.

codewhale exec [args]

The one-shot headless worker (stream-json, fleet subprocess, CI primitive) — not part of this API, but it shares the same runtime and event vocabulary.

Probe without model tokens

The stdio control transport can be probed without spending model tokens. capabilities returns the advertised method families (thread/*, app/*, prompt/*) and the full method list; the method set is pinned by a drift test in crates/app-server/src/lib.rs, so SDK and local integration clients can rely on it not changing silently.

printf '%s
' \
  '{"jsonrpc":"2.0","id":1,"method":"healthz"}' \
  '{"jsonrpc":"2.0","id":2,"method":"capabilities"}' \
  '{"jsonrpc":"2.0","id":3,"method":"shutdown"}' \
  | codewhale app-server --stdio

A live turn can be asked to stop with thread/interrupt (or POST /v1/threads/{id}/turns/{turn_id}/interrupt over HTTP); when no turn is streaming the reply carries interrupted: false — not an error, just nothing to stop.

Security boundary

The runtime API token is read from --auth-token, then CODEWHALE_RUNTIME_TOKEN, then DEEPSEEK_RUNTIME_TOKEN; --insecure-no-auth is only accepted with a loopback bind. Cross-origin browser requests are rejected by the CORS allow-list. Before selecting a non-loopback bind — especially app-server --mobile — read the full deployment and authentication contract in docs/RUNTIME_API.md.

Source document: docs/RUNTIME_API.md · Update docs-map.ts when changing.

Find the guidance you need.