Skip to main content
Use these routes to manage the runtimes Clawboo runs agents on, other than OpenClaw: Clawboo Native (built in), Claude Code, Codex and Hermes. They list each runtime’s state, install a runtime, connect or disconnect its credentials, check a provider key, run a board task on a runtime, and read or control the Hermes gateway. The page also covers the provider-key routes behind Settings > Providers, the first-run onboarding routes, and the in-app ChatGPT sign-in.
OpenClaw runs as its own Gateway process that Clawboo starts and talks to, so these routes do not cover it and answer 404 for openclaw. Its install, setup and Gateway control are in the System API.
An unknown :id answers 404 { "error": "unknown runtime '<id>'" }. Request bodies are JSON (up to 2 MB). Every route counts against the general rate limit of 3,000 requests a minute per client address; routes marked sensitive below also count against a limit of 60 a minute. Add the access cookie to each curl example (see Authentication).

Routes

POST /api/runtimes/:id/install and POST /api/auth/cli-login/:tool stream Server-Sent Events instead of returning a JSON body, so each is documented with an event catalog (event type and payload). Install answers a plain JSON 400 for the built-in Clawboo Native before any stream opens; cli-login answers a plain JSON 404 for an unknown :tool.

GET /api/runtimes

Lists every runtime with its capabilities, live health, and install and credential status. available[] describes the full catalog, so a client can show “available to add” cards for runtimes you have not connected yet. No key value is ever returned; the credential fields report presence only.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the runtime list plus the catalog:
steering is live for Claude Code, Codex, Hermes and Clawboo Native (a comment joins the running turn), and streaming is true for all four. toolApproval: true does not mean Clawboo asks before a tool runs: Claude Code and Codex run with their own approval prompts off, and Hermes asks only before the commands its own policy flags (see What agents can do). The status fields: connectionState is derived like this: With CLAWBOO_ENABLE_MOCK_RUNTIME=1, runtimes[] also lists a clawboo-mock fault-injection runtime for development. It is not in available[]. POST /api/runtimes/clawboo-mock/run runs a task on it; the other :id routes answer 404 for it. 500 Internal Server Error: a failure building an adapter or probing health:

Example


POST /api/runtimes/:id/install

Installs the runtime. Claude Code and Codex are pinned to a major version (for Claude Code, a 0.x minor line), and Hermes to one exact release. Each goes into Clawboo’s own runtimes folder, never npm’s global folder:
  • Claude Code: @anthropic-ai/claude-agent-sdk@0.3, the SDK every Claude Code run loads, not the claude CLI. A run loads it from the runtimes folder first, so this works whether the server runs from a global install, npx or a source checkout.
  • Codex: @openai/codex@0, with a codex launcher in the runtimes folder’s bin/ that runs it on the server’s Node.js.
  • Hermes: release 0.23.1 from its GitHub tag, at hermes/v0.23.1 in the runtimes folder. The server downloads the tag’s source and the uv (0.13.5) and CPython (3.14.9) builds that release pins for itself, checks each against its sha256, installs Hermes’s locked dependencies with uv sync --frozen, and checks that the new install reports 0.23.1 before it switches to it. No system Python, pip or pipx is used. When the Hermes gateway is running, starting, restarting or failed, the server restarts it on the new install before it sends complete; otherwise it starts it when you have Hermes agents. See Hermes.
For Claude Code and Codex, npm runs on the Node.js the server runs on, as npm install --prefix <new install folder> --include=optional --no-global --location=project --no-fund --no-audit <spec>, under umask 022 and without npm_config_global, npm_config_location and npm_config_prefix. On success the new install becomes current and the previous one is kept. A failed or stopped install is removed, and the current one is untouched. A Hermes install does the same with its own new folder. Clawboo Native is built in, so it answers 400 before any stream opens. If the client closes the connection, a first install of Claude Code or Codex is stopped; a Hermes install always runs to the end. An install over one that is already there (an update) runs to the end instead, since stopping it part way can leave the runtime half replaced. One install of a runtime runs at a time: a request while one is running answers with an INSTALL_RUNNING error. When Claude Code already has an Agent SDK with its own binary (in the runtimes folder or next to Clawboo), the stream sends one output line naming the binary and complete, and installs nothing.
  • Path params: id.
  • Request body: none.

Responses

400 Bad Request: the runtime is built in (no stream opens):
200 OK + text/event-stream: for an installable runtime the stream sends data: <json>\n\n frames.

Event catalog

The error codes: For Claude Code and Codex, a failed npm run ends the stream with one error whose code is npm’s own (else EXIT_<n>) and whose message reads Installation failed with exit code <n>. followed by npm’s reason. No install here suggests sudo. An Agent SDK install that npm finished without the SDK’s own binary ends with UNUSABLE instead of complete, and the install it would have replaced stays current. When an install succeeds but the runtime still reads not installed, complete carries a warning. For Hermes it says Clawboo will not run the new install from its runtimes folder, and to check that folder’s owner and permissions or set CLAWBOO_RUNTIMES_DIR to a folder of its own. A Hermes install that was running a gateway restarts it on the new install; when that restart fails, complete still reads success: true (the install stands), and its warning says the gateway did not start again, with the reason. For Codex it says the CLI is not on PATH or in the known user-install folders yet, and suggests restarting the server. Example frames:

Example


POST /api/runtimes/:id/connect

Connects a runtime. What it does depends on the runtime:
  • Codex takes no key. The route checks for an existing codex login, reports the state, and returns the command to sign in. To sign in from the dashboard, use POST /api/auth/cli-login/codex.
  • Claude Code stores apiKey under ANTHROPIC_API_KEY.
  • Hermes stores apiKey under OPENROUTER_API_KEY. Hermes also runs on an ANTHROPIC_API_KEY or OPENAI_API_KEY already stored, or on a ChatGPT sign-in.
  • Clawboo Native stores apiKey in the slot for provider (table below). With provider: "ollama" it records that you picked local Ollama and stores nothing. With a provider and no apiKey, it reuses a key that already exists for that provider.
  • Claude Code and Hermes with no apiKey and no provider reuse a key that already resolves for one of their variables, such as one a disconnect kept because another runtime reads it. With none, or with a provider, the answer is 400.
The key goes into Clawboo’s encrypted vault only; it is not copied to OpenClaw’s files (POST /api/providers/:id/connect does that). Every successful connect clears this runtime’s disconnect flag, so keys in the server’s environment and in ~/.openclaw/.env count for it again. The key is never echoed back.
  • Path params: id.
  • Request body:
How Clawboo Native maps provider to a vault slot: Any other value is refused with 400 and nothing is stored. That includes minimax, nvidia, huggingface and venice, which the Providers routes accept but Clawboo Native cannot run on. Key reuse. A Clawboo Native request with a provider and no apiKey reconnects with a key that already resolves for that provider, from the server’s environment, the vault or ~/.openclaw/.env. Nothing is stored. The dashboard’s Use button on a provider row (in Settings > Runtimes, under Clawboo Native’s Manage) sends this request after it checks the stored key with POST /api/runtimes/clawboo-native/healthcheck.

Responses

200 OK (Codex): the current state and the sign-in command:
200 OK (every other case): the key was stored, reused, or the Ollama choice recorded, and the state re-derived (normally ready):
400 Bad Request: apiKey is missing or blank and no provider was sent:
400 Bad Request: a provider was sent with no apiKey, and Clawboo Native has no existing key for it. Claude Code and Hermes always answer this when provider comes without a key. The server’s message contains an em dash, shown here as the JSON escape \u2014:
400 Bad Request (Clawboo Native): provider names a provider Clawboo Native cannot run on:

Example


POST /api/runtimes/:id/disconnect

Disconnects a runtime. With no body this is a full disconnect: the runtime stops using any key until it is connected again, and the vault keys only this runtime reads are deleted. The CLI stays installed. Clawboo Native also takes { "provider": "ollama" }, which removes only the local Ollama choice. The vault holds a single copy of each key for every runtime, so a full disconnect keeps any key another runtime also reads. GET /api/runtimes shows each runtime’s disconnectPlan beforehand, and the answer lists what was deleted and kept. To delete one provider’s key for every runtime, use POST /api/providers/:id/disconnect. A full disconnect also:
  • Sets the runtime’s disconnect flag. Until you connect this runtime again, it resolves no key at all: not a kept vault key, and not one in the server’s environment or in ~/.openclaw/.env.
  • Leaves the copies in ~/.openclaw/.env and in each OpenClaw agent’s auth-profiles.json alone. OpenClaw keeps those keys, and other runtimes that are not disconnected still find them there.
  • Stops memory embeddings from using a deleted key.
For Clawboo Native, neither a later key connect nor OLLAMA_BASE_URL turns Ollama back on after a full disconnect; only picking it again (a connect with provider: "ollama") does. { "provider": "ollama" } removes only the Ollama choice and keeps every key. It also stops a configured OLLAMA_BASE_URL from counting as set up until Ollama is picked again. While Ollama is removed, no run uses it: an agent whose only provider is Ollama fails and reads providerReady: false, and an agent with a keyed fallback runs on the fallback. In the dashboard, a runtime’s Manage > Disconnect sends the full form. Under Clawboo Native’s Manage, Disconnect Ollama sends { "provider": "ollama" }, and the disconnect button on any other provider row (for example Disconnect OpenAI) calls POST /api/providers/:id/disconnect.
  • Path params: id.
  • Request body: none, or { "provider": "ollama" } for clawboo-native.

Responses

200 OK: done; the state re-derived:
400 Bad Request: provider was sent but is empty or not a string (it is never treated as a full disconnect):
400 Bad Request: a provider other than ollama, or ollama on a runtime other than clawboo-native:

Example


POST /api/runtimes/:id/logout

Signs Codex out by running the CLI’s own codex logout; Clawboo never deletes the vendor’s tokens itself. The answer comes from a fresh codex login status check, not from the command’s exit code. A runtime that authenticates with a key has no sign-out; use the disconnect route.
This signs out the ChatGPT sign-in that every tool on the machine shares, not only Clawboo’s use of it.
  • Path params: id.
  • Request body: none.

Responses

404 Not Found: the runtime does not use a sign-in:
400 Bad Request: the CLI is not installed:
200 OK: the fresh check. ok is true only when the sign-out took:

Example


POST /api/runtimes/:id/healthcheck

Checks a provider credential with one authenticated request to the provider’s model list, before anything relies on it. The key is used for that one request only: it is never stored, logged or echoed. A bad key or an unreachable provider comes back as { ok: false, error } with status 200. The dashboard calls this before it saves or reuses a key: on the onboarding connect step, in Providers, on a runtime’s connect card, and for Use on a provider row.
Only clawboo-native takes this route; any other valid :id answers 400. It checks a provider, not a runtime, so a key meant for another runtime is checked by naming its provider here.
  • Path params: id (must be clawboo-native).
  • Request body:
Where each provider is checked: anthropic at https://api.anthropic.com/v1/models, openai at https://api.openai.com/v1/models, openrouter at https://openrouter.ai/api/v1/models, the OpenAI-compatible providers (google, xai, groq, mistral, together, cerebras, moonshot) at their own <base URL>/models, and ollama at /api/tags on OLLAMA_BASE_URL (a trailing /v1 removed), else http://localhost:11434. The request times out after 8 seconds and refuses redirects.

Responses

400 Bad Request: :id is not clawboo-native:
400 Bad Request: unknown provider:
400 Bad Request: a keyed provider with no apiKey and no key that resolves for it:
200 OK: the provider answered and accepted the key:
200 OK: the check failed (the failure is in the body):
For ollama, model matches the way Ollama resolves names: an untagged llama3.2 is met by llama3.2:latest, a tagged qwen2.5:7b only by itself. An answer that is not a tags list proves nothing either way, so it passes.

Example


POST /api/runtimes/:id/run

Runs one board task on the runtime from start to finish: claim the task, prepare its workspace, run the agent, and report the result. The request stays open for the whole run. If the client disconnects first, the run and its process are stopped and the task goes back to todo. The runtime’s MCP clients attach to this server’s own /api/mcp/* routes on its loopback port, never to the request’s Host. The runtime’s keys are read the way its card reads them: from the server’s environment, the vault, then ~/.openclaw/.env, or from the vault only after a disconnect. Codex gets no key; it uses its own sign-in. This route is one of the two ways work runs through Clawboo’s task runner (the other is an agent Routine), so it gets the runner’s extras: a git worktree when the task needs one, verification of the worktree’s changes, memory injection and circuit breakers. Team chat does not run through it; see How a team works and When work is checked.
  • Path params: id.
  • Request body:
A code task (or any kind other than research and review) changes files, so it needs a worktree. A task that already has a worktree reuses it, rebuilding it from the task branch if it was cleaned up. A checkout still on the task branch with nothing uncommitted is reused as it is. A rebuild never replaces a folder that holds uncommitted changes, files git ignores, a commit no branch holds, a separate repository, or contents git cannot read: the run is refused with workspace_unavailable, and the task moves to blocked with a [blocked: worktree kept] comment naming the folder. When git does not answer the check, the run is refused the same way, nothing is changed, and the task goes back to todo. Otherwise, with no repoPath, or when the worktree cannot be created, the run is refused with workspace_unavailable: the task gets a [blocked: no isolation] comment and goes back to todo. A research or review task gets no worktree and starts in the task’s own folder, <work folder>/teams/<teamId>/tasks/<taskId> (teams/_no-team/tasks/<taskId> for a task with no team), and is told to save the files it makes for the task there and that the team’s shared folder is two levels up (../..); if that folder cannot be created, the run is refused with workspace_unavailable too. A worktree keeps file changes apart; neither it nor the task’s folder is a sandbox (see What agents can do).

Responses

A refused or finished run answers with the runner’s result. A refusal (ok: false) maps to a status by its reason: not_found is 404, conflict is 409, and every other reason is 422. 400 Bad Request: missing taskId:
400 Bad Request: assigneeAgentId is not a bare identifier:
200 OK: the task ran:
When verification fails, the route runs the task again with the failure in its prompt, inside the same request, before it answers. It allows one fix run by default (CLAWBOO_MAX_FIX_CYCLES changes the number), so the answer describes the last run. How each runtime’s cost is reported or estimated is in Budgets and spend. 404 Not Found: no task with that id:
409 Conflict: the task could not be claimed (someone else holds it). Treat it as data and do not retry:
Without the person check, a 409 also says this run would undo something: person_moved while a person’s move of the card stands, or why the board would not start the task by itself, such as stopped after a Stop, failed_too_often or budget, or job_limit when the job has started as many runs by itself as it may. Such a run counts toward that limit. A person can run it anyway, and a person’s run does not count. 422 Unprocessable Entity: the run was refused before it started:
500 Internal Server Error: an unexpected error inside the run:

Example


GET /api/runtimes/openrouter/models

The live OpenRouter catalog behind the OpenRouter model pickers. It reads OpenRouter’s public model list (no key), keeps text models, sorts them by label, and caches the list for 30 minutes, with an 8-second fetch timeout.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the catalog. This route does not fail: a failed or empty fetch falls back to the last good list, and an empty array tells the client to use its own built-in list:

Example


GET /api/runtimes/codex/models

The models your ChatGPT plan can run, behind the ChatGPT subscription groups of the OpenClaw and Hermes model pickers and the default model the OpenClaw setup writes for a ChatGPT sign-in. Clawboo names none of these models itself: OpenAI decides which models each ChatGPT plan may use, and the list changes. The route asks your own Codex CLI. When codex login status reports a sign-in, it runs codex app-server in your ~/.codex (or CODEX_HOME) and pages through model/list, so the CLI fetches the list with its own sign-in; Clawboo never reads a token. It also reads models_cache.json in the same folder, the list a Codex CLI last fetched there, and uses it when the CLI could not fetch a fresh one. An old Codex CLI that cannot read the current list answers with the models it shipped with; that answer is never used, and updateRequired is set instead. The result is cached for 10 minutes (1 minute when empty) and dropped after Codex is installed or signs in or out.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: this route does not fail. An empty models means the list is unknown; the pickers then offer only the plan’s default, which each CLI resolves for itself:

Example


GET /api/runtimes/hermes/gateway

The state of the Hermes gateway: the one long-lived Hermes process every Hermes agent runs through, which Clawboo starts, restarts after a crash and stops with itself. The Runtimes card’s Gateway section for Hermes reads it. See The Hermes gateway.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the status. It never carries a key:
not-installed means Clawboo has no install of Hermes of its own. failed means it could not start, or exited and is not being restarted (a config Hermes refuses, or ten restarts in a row); the next Hermes run or a start tries again.

Example


POST /api/runtimes/hermes/gateway

Starts, restarts or stops the Hermes gateway. Clawboo starts it by itself when a Hermes agent runs, and at launch when there are Hermes agents, so these are manual controls. A stopped gateway runs no Hermes agent and fires none of their own jobs until something starts it again.
  • Path params: none.
  • Request body:

Responses

200 OK: done, with the new status:
400 Bad Request: action is missing or not one of the three:
502 Bad Gateway: the gateway could not start, with the reason and the status:

Example


Onboarding

The three /api/onboarding/* routes take no :id. They are grouped here because they are Clawboo Native’s first-run routes. Onboarding creates no team of its own: you pick one in the marketplace and deploy it through the Teams API.

POST /api/onboarding/native-leader-model

Records the provider and model you picked when you connected a native provider (a key, or keyless Ollama), or later with Make default in Clawboo Native’s provider list. Boo Zero runs on it when Clawboo creates it (if that provider can still run), and an existing native Boo Zero is switched to it. New native agents created without a model pick follow it while its provider stays set up: a leader runs the recorded model, and a specialist runs that provider’s cheaper default (on Ollama, the recorded model too). See Clawboo Native. Body { provider, model }.
  • 200 OK: { "ok": true }.
  • 400 Bad Request: { "error": "unknown provider '<provider>'" } when provider is not one of the eleven native providers (the table under connect, including ollama), or { "error": "model is required" } when model is missing or blank.
  • 500 Internal Server Error: { "error": "<message>" } when the setting cannot be written.

GET /api/onboarding/native-leader-model

The recorded pick, plus what a native agent created without a model pick would get right now, per tier. The native provider manager reads it for its Default tag and model menu, and the team-deploy dialog labels each native member left on Default with it.
resolved comes from the same logic agent creation uses, including the check that an Ollama model is pulled. A recorded value that cannot be read counts as no pick. This route does not return an error status.

GET /api/onboarding/state

The first-run signals in one call, so a client can decide between the setup wizard and the dashboard without several requests:
hasConnectedRuntime is true when any of the four runtimes has one of its keys in the vault, when Codex is signed in, or when Hermes holds a ChatGPT sign-in. A key that exists only in the server’s environment does not count, and neither does a keyless Ollama choice. 500 { "error": "<message>" } on an unexpected error.

Providers

The /api/providers* routes back Settings > Providers. A provider is a model vendor (anthropic, openai, …), not a runtime: one Anthropic key can serve Clawboo Native, Claude Code, Hermes and OpenClaw at once. These routes keep the key in two places, so that every runtime finds it:
  • Clawboo’s encrypted vault (read by Clawboo Native, Claude Code and Hermes).
  • OpenClaw’s own key files, in plain text and owner-only (mode 0600): ~/.openclaw/.env and every existing OpenClaw agent’s auth-profiles.json (as the <provider>:default profile). The folder is created (mode 0700) if it does not exist, even when you do not use OpenClaw.
For where keys are stored and how to connect them in the dashboard, see Providers and runtimes. The 14 providers and their key variables: anthropic (ANTHROPIC_API_KEY), openai (OPENAI_API_KEY), google (GEMINI_API_KEY), openrouter (OPENROUTER_API_KEY), xai (XAI_API_KEY), groq (GROQ_API_KEY), mistral (MISTRAL_API_KEY), moonshot (MOONSHOT_API_KEY), minimax (MINIMAX_API_KEY), together (TOGETHER_API_KEY), nvidia (NVIDIA_API_KEY), huggingface (HF_TOKEN), cerebras (CEREBRAS_API_KEY), venice (VENICE_API_KEY). ollama and openai-codex (the ChatGPT sign-in) are not providers here; connect answers 400 for them.

GET /api/providers

Every provider and whether it has a key:
poweredRuntimes names every runtime that reads this provider’s key: a runtime is listed when the key’s variable is one it reads (the variables in the disconnect table above), and OpenClaw is listed for every provider. It says which runtimes can use the key, not that they are installed or connected.

POST /api/providers/:id/connect

Body { apiKey }. Stores the key in the vault and writes it to ~/.openclaw/.env and every OpenClaw agent’s auth-profiles.json, replacing an earlier key for the same provider. Memory embeddings may switch to the new key. Returns { ok: true, providers } with the refreshed list. The dashboard’s Providers page and the OpenClaw setup’s key prompt call this route.
  • 400 Bad Request: { "error": "unknown provider '<id>'" }, or { "error": "apiKey is required" } when the key is missing or blank.

POST /api/providers/:id/disconnect

Removes the provider’s key from the vault, from ~/.openclaw/.env, and from every OpenClaw agent’s auth-profiles.json. A key exported in the server’s environment is not touched: runtimes can still use it, though the list shows the provider as not connected. Returns { ok: true, providers }.
  • 400 Bad Request: { "error": "unknown provider '<id>'" }.

GET /api/providers/:id/models

The provider’s live model list, fetched with the key that resolves for it (server environment, vault, then ~/.openclaw/.env). Returns { "models": [] } when there is no key or the provider has no live list here, so a client can fall back to its built-in list. Lists are cached for 30 minutes per provider and key, with an 8-second timeout; a failed fetch serves the last good list for the same key. ollama needs no key and answers from the local Ollama instead: its chat models (embedding-only models left out, models without tool support labelled (can't use tools), newest first), whether Ollama answered, and recommendedModel. That is llama3.2 when it is pulled; otherwise the newest pulled model that can use tools, then the newest whose tool support Ollama does not report, then the newest that cannot use tools; and llama3.2 itself when Ollama lists no chat model or does not answer. It does not read your recorded default. It is read fresh on every call, so a model you just pulled shows up.

POST /api/providers/:id/models

Body { apiKey }. The live model list using a pasted key that is not saved; the onboarding step calls it before any key is stored. The key is used for one fetch and is never logged, stored or echoed. Returns { "models": [] } when the provider has no live list (see the table; ollama included) or the key is blank.

POST /api/auth/cli-login/:tool

The dashboard’s Sign in with ChatGPT. Runs the official CLI’s own sign-in command on this machine and relays what it prints (a device code, a sign-in URL) over SSE. The sign-in itself stays inside the vendor’s CLI: you approve it in a browser, and Clawboo never handles the tokens. Only one sign-in runs per tool; a new request stops the previous one first. A sign-in is stopped after 16 minutes, since the CLIs’ own device codes expire after 15.
  • Path params: tool.
  • Request body: none.

Responses

404 Not Found: unknown :tool, as plain JSON before any stream opens:
200 OK + text/event-stream: otherwise the stream sends data: <json>\n\n frames. A sign-in that cannot start (the CLI is not installed, or the OpenClaw sign-in on Windows) is an error frame inside the stream, not an HTTP error, so the dashboard can fall back to showing the command to copy.

Event catalog

The error codes: Completion comes from checking where the tool stores its sign-in (every 3 seconds), not from the exit code alone, because a browser sign-in can leave the CLI waiting at a prompt after the credential has landed. As soon as the credential appears, the stream sends complete with success: true, loggedIn: true and stops the command. If the command exits without a usable credential, complete carries success: false, loggedIn: false and a message naming the command to run in a terminal. Cancelling in the dashboard closes the connection, which stops the command and everything it started.

Example


Error envelope

Errors use the standard { "error": string } body, with three exceptions: healthcheck answers { "ok": false, "error": string } (its success body is { "ok": true }), a refused run answers { "ok": false, "reason": string }, and the two SSE routes report failures as error frames once the stream is open. Going over a rate limit answers 429 with { "error": "Too many requests. Wait a moment and retry." } (general) or { "error": "Too many requests for this operation. Wait a moment and retry." } (sensitive), plus a Retry-After header. Source of truth: apps/web/server/api/runtimes.ts, hermesGateway.ts, providers.ts, onboardingSeed.ts, onboardingState.ts and cliLogin.ts; key storage in apps/web/server/lib/secretsVault.ts, providerKeys.ts and openclawEnv.ts; runtime definitions in apps/web/server/lib/runtimes/descriptor.ts; the Hermes install and gateway in apps/web/server/lib/runtimes/hermes/.
Last modified on November 14, 2026