Clawboo Runtimes API: Connect, Install, and Run Agents

The Runtimes API covers the four non-OpenClaw runtimes (claude-code, codex, hermes, clawboo-native): listing their capabilities and connection state, installing their CLI, storing provider keys in the encrypted vault, verifying a key before persisting it, and driving a board task end-to-end on a chosen runtime. This group also covers POST /api/onboarding/seed-native-team, which mints a default native leader + specialist team for first-run users.

OpenClaw is not in this group — it is a connected substrate driven over the Gateway, not a CLI you install or a key you paste. Any route in this group returns 404 for the openclaw id. See the System API for OpenClaw lifecycle and the Agents API for the agent registry.

An unknown :id returns 404 { "error": "unknown runtime '<id>'" } on every route.

Routes

Method	Path	Summary
`GET`	`/api/runtimes`	List runtimes with capabilities, health, and connection state
`POST`	`/api/runtimes/:id/install`	Install the runtime CLI (SSE)
`POST`	`/api/runtimes/:id/connect`	Store a provider key in the encrypted vault
`POST`	`/api/runtimes/:id/disconnect`	Clear the stored credential
`POST`	`/api/runtimes/:id/healthcheck`	Verify a pasted key without persisting it
`POST`	`/api/runtimes/:id/run`	Drive a board task on this runtime end-to-end
`POST`	`/api/onboarding/seed-native-team`	Mint a default native leader + specialist team

`GET /api/runtimes`

Lists every runtime with its capabilities, live health, and install/auth status. The available[] array advertises the full catalog for runtimes the user has not yet connected.

Response `200 OK`

runtimes

array

Connected runtimes with their full status.

Show Runtime fields

string

'claude-code' | 'codex' | 'hermes' | 'clawboo-native'

name

string

Human-readable runtime name.

installed

boolean

true for clawboo-native (built-in) and for others when their CLI is found on PATH.

hasCredential

boolean

Whether a credential is present (presence only — the value is never returned).

hasVaultCredential

boolean

Whether a credential was deliberately connected via the vault (ignores bare env vars).

connectionState

string

'not-installed' | 'needs-auth' | 'needs-login' | 'ready' | 'unknown'

authKind

string

'api-key' | 'oauth' | 'none'

health

object

{ ok: boolean, message?: string }

capabilities

object

Runtime capability flags (streaming, MCP, worktrees, resume, etc.).

builtIn

boolean

true for clawboo-native.

installCommand

string | null

e.g. 'npm install -g @anthropic-ai/claude-code'

available

array

Full runtime catalog including runtimes not yet connected.

curl http://localhost:18790/api/runtimes

`POST /api/runtimes/:id/install` (SSE)

Installs the runtime’s CLI. npm runtimes (claude-code, codex) run npm install -g <pkg>. The pip runtime (hermes) uses pipx install with a fallback to pip install --user. The built-in clawboo-native returns 400 before any stream opens. The response is Server-Sent Events (Content-Type: text/event-stream). Use curl -N to stream the output. Each frame is data: <json>\n\n.

Event catalog

`type`	When	Payload fields
`progress`	Install start, and on PEP-668 retry	`step` (`'installing'`	`'retrying'`), `message`
`output`	Per stdout/stderr line	`line`
`error`	Tooling missing, permission denied, or non-zero exit	`code`, `message`
`complete`	Process exits 0	`success: true`, optional `warning`

Terminal error codes:

Code	Meaning
`NPM_MISSING`	`npm` not found
`PYTHON_MISSING`	Python 3 with pip/pipx not found
`EACCES`	Permission denied
`SPAWN_THROW`	The spawn call threw synchronously
`EXIT_<n>`	Non-zero process exit

curl -N -X POST http://localhost:18790/api/runtimes/claude-code/install

Example SSE frames:

data: {"type":"progress","step":"installing","message":"Installing Claude Code…"}

data: {"type":"output","line":"added 1 package in 3s"}

data: {"type":"complete","success":true}

`POST /api/runtimes/:id/connect`

Stores a provider key in the encrypted vault and marks the runtime connected. The key is never echoed in the response. For the OAuth runtime (codex), this is a no-op that returns the terminal login command instead.

Request body

apiKey

string

Required for api-key runtimes. Must be non-empty.

provider

string

For clawboo-native only: routes the key to a specific provider ('anthropic', 'openai', 'openrouter', 'ollama'). Omit to store under ANTHROPIC_API_KEY.

Responses

200 OK — key stored, runtime is ready:

{ "ok": true, "connectionState": "ready" }

200 OK — Codex (OAuth) returns the login command:

{ "ok": true, "connectionState": "needs-login", "loginCommand": "codex login" }

For clawboo-native, pass provider: "openrouter" to store an OpenRouter key, or provider: "ollama" for a keyless Ollama configuration.

# Claude Code
curl -X POST http://localhost:18790/api/runtimes/claude-code/connect \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-ant-..."}'

# Native runtime with OpenRouter
curl -X POST http://localhost:18790/api/runtimes/clawboo-native/connect \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-or-...","provider":"openrouter"}'

`POST /api/runtimes/:id/disconnect`

Clears the stored credential for the runtime. The binary stays installed; the card returns to needs-auth.

Response `200 OK`

{ "ok": true, "connectionState": "needs-auth" }

curl -X POST http://localhost:18790/api/runtimes/hermes/disconnect

`POST /api/runtimes/:id/healthcheck`

Verifies a pasted provider key with a single authenticated GET to the provider’s models endpoint. The key is used once and never persisted. A bad key or unreachable provider resolves to { ok: false, error } — the handler never throws into the request.

This route is native-only (clawboo-native). Any other valid runtime id returns 400 { "ok": false, "error": "healthcheck is only supported for the native runtime" }.

Provider → probe endpoint mapping:

Provider	Endpoint
`anthropic`	`https://api.anthropic.com/v1/models`
`openai`	`https://api.openai.com/v1/models`
`openrouter`	`https://openrouter.ai/api/v1/models`
`ollama`	`<OLLAMA_BASE_URL>/api/tags` (keyless)

The fetch is bounded by an 8-second timeout.

Request body

provider

string

One of 'anthropic', 'openai', 'openrouter', 'ollama'. Defaults to 'anthropic'.

apiKey

string

Required for all providers except 'ollama'.

Responses

200 OK — provider reachable, key authenticated:

{ "ok": true }

200 OK — provider rejected the key or was unreachable (note: still HTTP 200):

{ "ok": false, "error": "Invalid API key." }
{ "ok": false, "error": "Could not reach anthropic (timed out)." }

curl -X POST http://localhost:18790/api/runtimes/clawboo-native/healthcheck \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-..."}'

`POST /api/runtimes/:id/run`

Drives a board task on the runtime end-to-end: claim → worktree → run → report-up, via the server-side executor runner. The runtime’s MCP client attaches to this server’s /api/mcp/* over a server-trusted loopback URL. If the client disconnects before the run finishes, the run and its subprocess are aborted and the task is released.

A 409 from this route means the task could not be atomically claimed — another worker holds it. Do not retry. See the 409 no-retry rule.

Request body

taskId

string

required

The board task to run.

assigneeAgentId

string

The agent id to assign. Defaults to the runtime id. Must match /^[A-Za-z0-9_-]+$/.

repoPath

string

Absolute path to the git repo to branch the worktree from.

kind

string

Task kind → isolation. Defaults to 'code'.

model

string

Model override for this run.

keepForResume

boolean

Pause the worktree and release the task for cross-runtime handoff instead of completing it.

Responses

200 OK — the task ran:

{
  ok: true
  runtimeId: string
  execId: string
  doneReason: 'success' | 'max_turns' | 'aborted' | 'error'
  status: string
  summary: string
  costUsd: number | null
  usedWorktree: boolean
  degradations: string[]
}

409 Conflict — the task could not be claimed — do not retry:

{ "ok": false, "reason": "conflict" }

422 Unprocessable Entity — run refused for a board/runtime reason (reason is one of too_deep, connected_substrate, budget_paused). connected_substrate means the target runtime is a connected substrate and cannot be dispatched through this path:

{ "ok": false, "reason": "too_deep" | "connected_substrate" | "budget_paused" }

curl -X POST http://localhost:18790/api/runtimes/claude-code/run \
  -H 'Content-Type: application/json' \
  -d '{"taskId":"<task-uuid>","repoPath":"/path/to/repo","kind":"code"}'

`POST /api/onboarding/seed-native-team`

Mints a default native team — a leader (tasks tool enabled, capable model) and a specialist (cheaper model) — for a first-run user who just connected a provider key. Both agents are clawboo-native rows created through the native AgentSource (no Gateway, no provider SDK call). The Know Your Team onboarding flags are pre-satisfied so the user lands straight in chat.

This route is not under /api/runtimes and takes no :id segment.

Request body

provider

string

Provider to use. One of 'anthropic', 'openai', 'openrouter', 'ollama'. Defaults to 'anthropic'.

model

string

Optional leader-model override. The specialist keeps its provider default.

Per-provider default models:

Provider	Leader	Specialist
`anthropic`	`claude-sonnet-4-6`	`claude-haiku-4-5`
`openai`	`gpt-4o`	`gpt-4o-mini`
`openrouter`	`anthropic/claude-haiku-4.5`	`openai/gpt-4o-mini`
`ollama`	`llama3.2`	`llama3.2`

Response `201 Created`

{ "teamId": "...", "leaderAgentId": "...", "specialistAgentId": "..." }

curl -X POST http://localhost:18790/api/onboarding/seed-native-team \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic"}'

​Routes

​GET /api/runtimes

​Response 200 OK

​POST /api/runtimes/:id/install (SSE)

​Event catalog

​POST /api/runtimes/:id/connect

​Request body

​Responses

​POST /api/runtimes/:id/disconnect

​Response 200 OK

​POST /api/runtimes/:id/healthcheck

​Request body

​Responses

​POST /api/runtimes/:id/run

​Request body

​Responses

​POST /api/onboarding/seed-native-team

​Request body

​Response 201 Created

​See also

Routes

`GET /api/runtimes`

Response `200 OK`

`POST /api/runtimes/:id/install` (SSE)

Event catalog

`POST /api/runtimes/:id/connect`

Request body

Responses

`POST /api/runtimes/:id/disconnect`

Response `200 OK`

`POST /api/runtimes/:id/healthcheck`

Request body

Responses

`POST /api/runtimes/:id/run`

Request body

Responses

`POST /api/onboarding/seed-native-team`

Request body

Response `201 Created`

See also