/api/ on the same port as the dashboard. The dashboard itself runs on this API, so you can script anything you do in the app. Use this page for the rules every route shares; each resource page lists its routes with parameters, bodies, responses and an example.
At a glance
Check that the server is up (the response carries
"ok": true when no boot check failed). Without the cookie the answer is a 401 from the access gate, which also tells you Clawboo is running:
/api/* route needs the access cookie, so add it to each curl as shown under Authentication.
Base URL
The server picks its port at startup. It tries18790 first and scans up to 18809 (20 ports), binding the first free one. Three environment variables change that:
After binding, the server writes the port to
<clawboo home>/api-port.txt (~/.clawboo/api-port.txt unless CLAWBOO_HOME is set), and from 0.9.0 the start marker api-port.json beside it, which names the server’s process so a reader can tell a running server’s record from a dead one’s. The CLI reads them to find a running server; see CLI.
Serving under a path prefix
SetCLAWBOO_BASE_PATH (for example /clawboo) to serve the app under a prefix, typically behind a reverse proxy. The API then answers at /clawboo/api/..., and it still answers at the unprefixed /api/..., which the CLI, agent MCP connections and the update check use on the loopback port. The access cookie’s Path follows the prefix.
The value must be one or more segments of A-Z a-z 0-9 . _ ~ - and must not start with api. A malformed value stops the server at startup with a SECURITY/CONFIG error.
Host binding
The server listens on loopback (127.0.0.1) by default, so other machines cannot reach it. Set HOST to listen on another interface (HOSTNAME is ignored).
A non-loopback bind with the access token turned off makes the server refuse to start (SECURITY: refusing to start, exit code 1). Keep the token on, or set CLAWBOO_ALLOW_INSECURE=1 to run open on purpose. Self-host securely walks through a safe remote setup.
Authentication
Clawboo has no user accounts. The only credential is the access token, which the server picks at startup:STUDIO_ACCESS_TOKENset: that token.- Unset (the default): the per-install token in
~/.clawboo/access-token(underCLAWBOO_HOME), made on the first start and readable only by your user account. - Set blank (
STUDIO_ACCESS_TOKEN=): no token, so every route answers without credentials, unless the proxy identity lane isrequired: then every/api/request still needs a verified identity token from your sign-in proxy. This relies on the loopback bind; the same-origin guard still refuses cross-origin browser requests.
/api/* request and the WebSocket need a clawboo_access cookie whose value is the token.
A browser gets the cookie from a one-time sign-in link, which clawboo, clawboo open and the dashboard’s Open on another device make, or by opening http://127.0.0.1:18790/?access_token=<token> once. The server answers 302, sets the cookie (HttpOnly, SameSite=Lax, Path=/ or the base path, plus Secure when the request arrived with X-Forwarded-Proto: https) and redirects to the same URL without the code or token.
A script sends the cookie itself. Add -b to any example on these pages:
-b "clawboo_access=$STUDIO_ACCESS_TOKEN". Send the cookie to 127.0.0.1, the address Clawboo listens on: localhost can resolve to ::1, where another program could be listening on the same port. On a computer other people use, the token also shows in the process list while curl runs.
One-time sign-in codes. POST /api/access/launch-code, behind the cookie like every other route, answers { "gated": true, "code": "…", "expiresAt": <epoch ms>, "expiresInMs": 120000 }, or { "gated": false } on a server with no token. Loading any page address with ?access_code=<code> in a browser sets the cookie once, within two minutes, when the request carries Sec-Fetch-Mode: navigate and Sec-Fetch-Dest: document. A request with no fetch metadata at all (browsers send none to a plain-HTTP network address) gets a 200 sign-in page whose button sends POST ?access_code=<code>, which sets the cookie with a 303. Only that form’s POST spends a code: form-encoded, with fetch metadata (if any) of a same-origin page navigation and an Origin (if any) of the dashboard itself. The dashboard’s locked screen sends the same POST for a link pasted into it, to ?signin=pasted&access_code=<code>; the redirect keeps signin=pasted. A fetch or a frame, and a used, expired or unknown code, get a redirect without the cookie; a code that was not spent stays live. A code is never accepted on an /api/ path. The route is on the sensitive rate limit.
Who is signed in. GET /api/access/identity answers { "proxyIdentity": "off" | "on" | "required", "appLink": boolean, "roles": "off" | "enforce", "personCheck": "page" | "verified", "controlClaim": "off" | "required", "readerKey": boolean, "person": { "id", "name", "role" } | null, "you": { "id", "name", "role" } }: the proxy identity lane’s mode, whether an app that started Clawboo gave it a key, whether roles are enforced, who may act as a person and whether a take over needs the proxy’s control claim (both from 0.9.0; see Only signed requests act as a person), whether a program beside Clawboo may make its own reads with a reader key (readerKey, from 0.9.0), the person the request’s verified identity token names, and who “you” means on the board: that person, else the install’s built-in person ({ "id": "local", "name": "You", "role": null }). With roles enforced it also carries access, what this person may do, and a request their role does not allow gets 403 with "error": "role" and a reason. With the lane required, every /api/ request also needs a good token from your sign-in proxy, or from the app that started Clawboo when it gave Clawboo a key (never on the Gateway WebSocket), and one that does not verify gets 401 with "gate": "clawboo-proxy-identity" and a reason, in any mode.
Keep the token out of API URLs: any request whose URL carries access_token gets that 302 answer (or a 401 when the token is wrong) instead of the route’s response.
The token may contain only
A-Z a-z 0-9 . _ ~ -. With any other character the server does not start: it logs SECURITY: refusing to start and exits with code 1 on every bind, even with CLAWBOO_ALLOW_INSECURE=1. openssl rand -hex 24 makes a suitable token. The comparison is constant-time, and the /api/ prefix test ignores letter case.
Is the server up. From 0.9.0, GET or HEAD on /api/system/live, exactly, with no query, needs no cookie and no identity token: it answers 200 { "ok": true } and nothing about the install.
Agent MCP connections. An agent runtime that Clawboo starts reaches the four MCP endpoints (/api/mcp/tasks, /api/mcp/memory, /api/mcp/tools, /api/mcp/teamchat) without a cookie. It passes only with the attachToken Clawboo put in its attach URL, and only when it connects straight to the loopback port with no proxy forwarding headers. /api/mcp/config and POST /api/mcp/attach-secret/rotate always need the cookie. See Tools and MCP.
Same-origin guard
Every/api/* request passes an origin check before the token check, whether or not a token is set. The guard answers 403 with { "error": "Cross-origin request blocked." } unless all three headers pass:
curl and other non-browser clients send no
Origin or Sec-Fetch-Site, so a local script passes. A refused WebSocket upgrade gets 403 Forbidden with no body.
The guard is not authentication: a non-browser client can send any headers it likes. Use the access token for that.
When clients reach the server by another name (a LAN address, or a reverse proxy that passes its own host name), add that name to CLAWBOO_ALLOWED_HOSTS. For a browser on that origin, also add the full origin (for example https://clawboo.example.com) to CLAWBOO_ALLOWED_ORIGINS. Both take comma-separated lists, and both only widen the allowlist.
CORS. A built app serves the dashboard and the API from one origin, so it sends no CORS headers. In dev (--dev, with Vite on port 5173), the server answers credentialed CORS requests only from origins the guard allows; it never reflects an arbitrary origin.
Requests and responses
- Bodies are JSON (
Content-Type: application/json), parsed once for every route with a 2 MB limit. Malformed JSON gets400and a larger body gets413. Both come from the body parser before any route runs, with an HTML error page rather than a JSON body. - Paths are case-sensitive.
/api/agentsmatches;/API/agentsdoes not. - Unknown paths. In a built app, a
GETto an unknown/api/path returns the dashboard page (HTML,200), because the page fallback answers every unmatchedGET. Other methods get404. When a call returns HTML, check the path. - Long requests. Some routes hold the connection open until work finishes, for example
POST /api/runtimes/:id/runandPOST /api/governance/delegation-approval. Their pages say so.
Rate limits
Two ceilings apply. Both count requests in memory, per client address, over a 60-second window.
Responses carry
RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (IETF draft 6). A 429 also carries Retry-After in seconds. On a sensitive route these headers describe the sensitive budget. The dashboard’s page and asset files have their own ceiling and do not count against the API.
The client address is the TCP peer. X-Forwarded-For is ignored, so behind a reverse proxy every client shares the proxy’s budget.
From 0.9.0, GET /api/system/live, which anyone may ask without signing in, has a ceiling of its own instead: 600 requests a minute per client address, with no rate-limit headers. It never counts against the general tier, so callers that have not signed in cannot use up the budget the dashboard shares behind a reverse proxy.
The sensitive tier covers the routes that install software, rewrite runtime configuration, start sign-ins or grant access:
Every other route is on the general tier, including routes that start work, such as
POST /api/runtimes/:id/run, POST /api/teams/:id/chat and the MCP transports. For what to do when the dashboard shows “Too many requests”, see Troubleshooting.
Errors
A JSON error body carries a human-readableerror string. Many routes add fields (zod details on a validation failure, findings, reason, code), and some answer { "ok": false, "error": "..." }. Each resource page lists its shapes. Three kinds of failure are not this JSON: body-parser errors (HTML, see above), the MCP transports (JSON-RPC error objects), and the SSE routes, which report a failure as a frame inside the stream once it has opened.
Streaming routes
Eleven routes answer with Server-Sent Events (Content-Type: text/event-stream) and write data: <json> frames. Each page documents its frames.
The three tail routes (the two chat streams and the event stream) put an
id: line on every stored row, so an EventSource resumes from Last-Event-ID after a reconnect. They start in different places when you send no cursor: the chat streams start at the newest message and send only what follows, while the event stream replays the whole log for its scope first. The chat streams open with a cursor event whose id: is where they start, so a connection that drops before its first message still resumes from there. A streaming route can still answer with a JSON error before the stream opens (for example 409 from the model install). The GET routes of the MCP transports are also event streams, but they carry MCP JSON-RPC, not Clawboo frames.
WebSocket: the Gateway proxy
/api/gateway/ws is the one WebSocket route. It carries the dashboard’s connection to the OpenClaw Gateway through the server, which adds the Gateway token and Clawboo’s signed device identity to the upstream connect frame, so the browser never sees the Gateway token. The route also answers at <base path>/api/gateway/ws; any other upgrade is closed.
The same-origin guard runs on the upgrade first (403 Forbidden on failure), then the access gate (with a token set, a missing cookie closes the socket). The frames are the Gateway’s own protocol; see Gateway and events.
Versions and features
A script or app that talks to more than one Clawboo server should not guess what each one supports.GET /api/system/capabilities (see System) answers with the server’s version, its client API revision, the oldest release whose clients it still serves, and a feature flag for each optional surface. A server supports clients of its current and previous minor release; see Supported versions.
Something that stops or restarts a server (a stop script, an updater, a process manager) can ask it to hold first, so it starts no new agent run, and wait for the runs going to finish. See Drain and hold.
Route index
The router registers 297 routes: 127GET, 116 POST, 25 DELETE, 15 PUT, 14 PATCH. Each belongs to one page:
Source of truth for maintainers: the router
apps/web/server/api/index.ts, the middleware order in apps/web/server/index.ts, apps/web/server/lib/rateLimit.ts, and packages/gateway-proxy/src/access-gate.ts and origin-guard.ts. apps/web/server/api/__tests__/clientContract.test.ts pins every route and method, so removing or renaming one fails it unless the API revision goes up.
Related
- Self-host securely: reach Clawboo from another machine with a token and the allowlists.
- Security: the access gate, the same-origin guard and what each protects.
- Environment variables:
STUDIO_ACCESS_TOKEN,HOST, the port and allowlist variables. - Limits and defaults: every limit and timeout in one table.
- MCP tools: the tools agents call over the MCP transports.