| 1 | import type { DocsRuntimeApiDict } from "../types"; |
| 2 | |
| 3 | /** |
| 4 | * English reference dictionary for `app/[locale]/docs/runtime-api/page.tsx` |
| 5 | * ("Automate with the Runtime API"). Checked against docs/RUNTIME_API.md |
| 6 | * (entrypoints, defaults, auth, endpoints) and the handlers in |
| 7 | * crates/tui/src/runtime_api.rs (`POST /v1/threads` → 201 ThreadRecord). |
| 8 | */ |
| 9 | export const docsRuntimeApi: DocsRuntimeApiDict = { |
| 10 | metaTitle: "Automate with the Runtime API · Codewhale Docs", |
| 11 | metaDescription: |
| 12 | "Drive Codewhale from your own scripts and apps: run one-shot prompts in CI, or start the local HTTP API and send turns, stream events, and answer approvals.", |
| 13 | bodyClassName: "text-ink-soft leading-relaxed", |
| 14 | title: "Automate with the Runtime API", |
| 15 | lede: |
| 16 | "Scripts and apps can drive the same engine you use in the terminal. For a single job, use `codewhale exec`. For an app that needs threads, live events, and approvals, run the local Runtime API. Everything runs on your machine; there is no hosted relay.", |
| 17 | sections: [ |
| 18 | { |
| 19 | id: "exec", |
| 20 | title: "Run one job from a script", |
| 21 | blocks: [ |
| 22 | { |
| 23 | code: `codewhale exec "Reply with exactly: pong" |
| 24 | codewhale exec --auto "fix the failing test and run it again" |
| 25 | codewhale exec --auto --output-format stream-json "update the changelog"`, |
| 26 | lang: "Terminal", |
| 27 | }, |
| 28 | { |
| 29 | p: "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](/docs/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.", |
| 30 | }, |
| 31 | ], |
| 32 | }, |
| 33 | { |
| 34 | id: "start", |
| 35 | title: "Start the Runtime API", |
| 36 | blocks: [ |
| 37 | { |
| 38 | code: `export CODEWHALE_RUNTIME_TOKEN="$(openssl rand -hex 32)" |
| 39 | codewhale app-server --http # http://127.0.0.1:7878`, |
| 40 | lang: "Terminal", |
| 41 | }, |
| 42 | { |
| 43 | p: "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.", |
| 44 | }, |
| 45 | ], |
| 46 | }, |
| 47 | { |
| 48 | id: "turn", |
| 49 | title: "Send a turn and watch it", |
| 50 | blocks: [ |
| 51 | { |
| 52 | code: `API=http://127.0.0.1:7878 |
| 53 | AUTH="Authorization: Bearer $CODEWHALE_RUNTIME_TOKEN" |
| 54 | |
| 55 | THREAD=$(curl -s -X POST "$API/v1/threads" -H "$AUTH" \\ |
| 56 | -H "Content-Type: application/json" -d '{}' | jq -r .id) |
| 57 | |
| 58 | curl -s -X POST "$API/v1/threads/$THREAD/turns" -H "$AUTH" \\ |
| 59 | -H "Content-Type: application/json" -d '{"prompt": "Summarize README.md"}' |
| 60 | |
| 61 | curl -N "$API/v1/threads/$THREAD/events?since_seq=0" -H "$AUTH"`, |
| 62 | lang: "Terminal", |
| 63 | }, |
| 64 | { |
| 65 | p: "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.", |
| 66 | }, |
| 67 | { |
| 68 | rows: [ |
| 69 | ["Stop a turn", "`POST /v1/threads/{id}/turns/{turn_id}/interrupt`"], |
| 70 | ["Answer an approval", "`POST /v1/approvals/{approval_id}`"], |
| 71 | ["Steer a running turn", "`POST /v1/threads/{id}/turns/{turn_id}/steer`"], |
| 72 | ["List saved sessions", "`GET /v1/sessions`"], |
| 73 | ], |
| 74 | }, |
| 75 | { |
| 76 | p: "[docs/RUNTIME_API.md](https://github.com/codewhale-hq/CodeWhale/blob/main/docs/RUNTIME_API.md) lists every route, request body, and event.", |
| 77 | }, |
| 78 | ], |
| 79 | }, |
| 80 | { |
| 81 | id: "other", |
| 82 | title: "Pick another connection", |
| 83 | blocks: [ |
| 84 | { |
| 85 | rows: [ |
| 86 | ["codewhale app-server --stdio", "JSON-RPC over standard input and output, with no network listener. Good for an SDK or a local probe."], |
| 87 | ["codewhale serve --acp", "Agent Client Protocol for editors such as Zed."], |
| 88 | ["codewhale serve --mcp", "Offer Codewhale's tools to another MCP client. See [Connect tools with MCP](/docs/mcp)."], |
| 89 | ["codewhale web", "The built-in [browser client](/docs/web), on the same API."], |
| 90 | ["codewhale doctor --json", "Health and capabilities as JSON, with no secrets."], |
| 91 | ], |
| 92 | codeTerms: true, |
| 93 | }, |
| 94 | ], |
| 95 | }, |
| 96 | { |
| 97 | id: "security", |
| 98 | title: "Keep it private", |
| 99 | blocks: [ |
| 100 | { |
| 101 | list: [ |
| 102 | "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.", |
| 103 | "`--insecure-no-auth` is accepted only on a loopback address.", |
| 104 | "The API never returns your provider keys. Health and capability reports carry only metadata — no secrets, file contents, or messages.", |
| 105 | ], |
| 106 | }, |
| 107 | ], |
| 108 | }, |
| 109 | ], |
| 110 | next: [ |
| 111 | { |
| 112 | href: "/docs/web", |
| 113 | label: "Open the browser client", |
| 114 | note: "A ready-made client for the same API.", |
| 115 | }, |
| 116 | { |
| 117 | href: "/docs/hooks", |
| 118 | label: "Run commands on events", |
| 119 | note: "React to session events without writing a client.", |
| 120 | }, |
| 121 | { |
| 122 | href: "/docs/fleet", |
| 123 | label: "Run a workflow", |
| 124 | note: "Durable, multi-step runs you can check from any terminal.", |
| 125 | }, |
| 126 | ], |
| 127 | sourceNote: "Source document: docs/RUNTIME_API.md · Update docs-map.ts when changing.", |
| 128 | }; |
| 129 |