Before you begin
- Node.js 22.12 or newer. The
clawboocommand checks this and stops with a message on an older Node. - Clawboo installed with
npm install -g clawboo(Install Clawboo). The package holds the launcher, the server (dist/server.js), the dashboard files (dist/ui), the four MCP programs (dist/bin), and the agent host and container launcher for agent isolation (dist/agent-host.js,dist/clawboo-launch).
Ways to run it
Start with the launcher
- It looks for a Clawboo server that is already running (how it finds the port) and opens your browser at it. If that server runs an older version than the launcher, it offers to restart it:
-yrestarts without asking, and--no-version-checkskips the check. - If none is running, it starts the server in the background. The server’s working directory is your Clawboo folder (
~/.clawboo), and its output goes to~/.clawboo/server.log. - It waits up to 45 seconds for the server to answer, then opens
http://127.0.0.1:<port>/(plus yourCLAWBOO_BASE_PATH, when one is set) with a one-time sign-in code, so the browser gets the access cookie. It prints only the plain address.
clawboo stop stops it, and clawboo restart replaces it on the same port; see the CLI reference.
The launcher uses the same access token as the server: the
STUDIO_ACCESS_TOKEN from the shell you run it in, or the per-install token in ~/.clawboo/access-token when it is unset. A server the launcher starts inherits the shell’s environment, so both pick the same one, and clawboo stop, clawboo restart and clawboo open work. With a server started with a STUDIO_ACCESS_TOKEN the shell does not have, clawboo, clawboo stop and clawboo restart report that a server is running and requires an access token, and clawboo stop also prints a command that stops it by port. See Token-gated installs.Start the server directly
- It runs in the foreground and logs to the terminal.
NODE_ENV=productiongives plain JSON log lines, as with the launcher. - Ctrl+C stops it cleanly. It stops the agent processes it started, waits up to 5 seconds for them, and closes the database.
- Start it from your Clawboo folder, as the launcher does. Claude Code, Codex and Hermes do not start there: a run without a worktree (every team-chat turn, research and review tasks, and Routines you make in the dashboard) starts in its team’s folder, or in the task’s own folder inside it on a task, in the work folder,
~/clawboo-work/teamsby default. - The dashboard files come from the
uifolder next toserver.js.CLAWBOO_UI_DIRpoints somewhere else. If Clawboo cannot readindex.htmlthere, page loads answer503with “The Clawboo dashboard could not be read from disk. Check CLAWBOO_UI_DIR.” - MCP attach snippets. To make the stdio snippets from
GET /api/mcp/configname the bundled MCP programs, also setCLAWBOO_MCP_BIN_DIR="$(npm root -g)/clawboo/dist/bin", as the launcher does. - Faster starts. The launcher sets
NODE_COMPILE_CACHE=~/.clawboo/cache/compile, so Node keeps its compiled copy of the server between starts. Set it yourself to get the same, which matters most when something stops the server when idle and starts it on demand. - Signing in. Without
STUDIO_ACCESS_TOKEN, the server locks itself with the per-install token in~/.clawboo/access-tokenof the user account it runs as. Runclawboo openas that user to open a signed-in browser, orclawboo open --printfor a one-time link to open elsewhere.
Run it as a service
A service manager keeps the server running after you log out and restarts it if it crashes. On Linux with systemd, a user service looks like this:ExecStart with the output of command -v node and npm root -g. KillMode=mixed sends the stop’s SIGTERM to the server alone, which then stops the agent processes it started its own way: from 0.9.0 it gives the Hermes gateway the SIGINT that Hermes reads as a planned stop. With systemd’s default, every process of the service gets SIGTERM at once, and Hermes takes that for a crash. TimeoutStopSec=20 leaves room for the server’s stop, which takes about 11 seconds at most, before systemd kills what is left. Agents and connectors find programs through PATH. If Node, npm or your agent runtimes live outside the system folders (under nvm, for example), add an Environment=PATH=... line with your shell’s PATH.
Put your settings in the environment file, one NAME=value per line, and keep the file readable only by you:
openssl rand -hex 24 and save it in your password manager before you start the server. Use only letters, digits, ., _, ~ and -: with any other character the server refuses to start.
The file mode keeps other user accounts out of the file. Programs running as you, agents included, can still read it: the token guards the network and other accounts, not your own account. With CLAWBOO_AGENT_USER set and your home folder closed to other users, agents cannot. Leave STUDIO_ACCESS_TOKEN out and the server uses its per-install token file instead, with the same limits.
Then turn the service on, and let it run while you are logged out:
journalctl --user -u clawboo shows its log. On macOS, run the same server command under launchd, with the same working directory and variables. Under launchd there is no journal, so set StandardOutPath and StandardErrorPath in its plist to a log file (a full path, as launchd does not expand ~) and read that file.
Run it in a container with agents on their own user
In a container,clawboo-launch runs the server and its agents as two users, so agents cannot read Clawboo’s database, vault, key, settings or token. It works under --security-opt no-new-privileges, which rules out sudo, because it only drops privileges, once for each process, with setpriv or gosu. Make it the container’s entrypoint, run as root, with an init process (docker run --init, or tini):
- Two users in the image.
CLAWBOO_SERVER_USERruns the server andCLAWBOO_AGENT_USERruns every agent. Neither may be root, and they must differ. - Two folders. Keep the data folder and the work folder apart: two volumes, or two top-level folders with different owners, such as
/dataand/work. On the first start the launcher gives the work folder to the agent user. - Runtimes both users can run. Install Node and each runtime (Claude Code, Codex, Hermes) outside any one user’s home.
- One restart policy for both. When the server or the agent host exits, the launcher stops the other and every agent process, then exits, so the container’s restart policy starts both again.
clawboo agent-user plan prints instead.
Ports
The server writes the port it chose to
~/.clawboo/api-port.txt, and removes the file when it stops unless another instance has rewritten it. From 0.9.0 it also writes the start marker api-port.json, which names its process; something that finds the server through these files should check the marker before it trusts the port. Pin the port when something else must find the server, such as a reverse proxy. To run a second, separate instance, give it its own CLAWBOO_HOME and port.
Where the server keeps its files
Clawboo’s own data lives in your Clawboo folder,~/.clawboo by default (CLAWBOO_HOME moves it): the database, settings, the encrypted key vault and logs. Your agents’ work, task worktrees and each team’s folder with its task folders, lives in the work folder: ~/clawboo-work by default, <CLAWBOO_HOME>-work when CLAWBOO_HOME is set, or the folder CLAWBOO_WORK_DIR names. It must be outside the Clawboo folder, or the server refuses to start. In a container whose Clawboo folder is a volume, set CLAWBOO_WORK_DIR to a second volume or folder; when it is unset and the default cannot be created, Clawboo keeps new work in the Clawboo folder and logs a warning. Clawboo also writes to OpenClaw’s folder (~/.openclaw) when you connect a key under Providers, set up OpenClaw, or change OpenClaw settings from the dashboard. Data and state lists every file and covers backups and resets.
Logs
- A server the launcher started writes to
~/.clawboo/server.log. When the launcher starts a server and the log is over 5 MB, it first moves the old log toserver.log.1. - A direct start logs to its terminal, or to your service manager’s journal.
- An OpenClaw Gateway that Clawboo starts for you logs to
~/.clawboo/gateway.log. LOG_LEVELsets how much the server logs:infoby default,debugfor more.- After an in-app update, the new server’s output does not reach
server.log. Runclawboo restartto capture it again.
Update Clawboo
- In the dashboard
- With npm
- Under a service manager
When a newer version is on npm, an Update available chip appears at the bottom left. On a global npm install it reads Click to update: one click installs
clawboo@latest with npm, waits up to 10 minutes for the agent runs still going to finish (Restart now skips the wait), restarts the server on the same port and reloads the page. The restarted server keeps the node options the old one started with, such as --max-old-space-size. For an npx run, a source checkout, or a global install whose folders the server’s user cannot write (such as a root-owned /usr/local), the chip reads Copy command and copies the command to run instead. If npm fails, the chip shows npm’s reason; a permissions error suggests sudo npm install -g clawboo@latest.registry.npmjs.org for the latest version and keeps a successful answer for 6 hours. With CLAWBOO_DISABLE_SELF_UPDATE=1 it never asks, and the dashboard offers no update.
Pin settings for everyone
Admins who deploy Clawboo for a team can pin settings in one file. A pinned setting applies to everyone who uses the install, and Settings > System > Deployment shows it as “Set by your administrator” with no way to change it. Put the file at~/.clawboo/operator.json (inside CLAWBOO_HOME), or anywhere with CLAWBOO_OPERATOR_SETTINGS pointing at it:
- Every key also has an environment variable, and the variable wins over the file.
- Clawboo reads the file once at startup, so run
clawboo restartafter a change. It never writes the file. - A file it cannot trust stops the server at startup with
CONFIG: refusing to start.and the reason: invalid JSON, an unknown key, a value of the wrong type, a file any user can write, or aCLAWBOO_OPERATOR_SETTINGSthat names a missing file. Starting anyway would drop the pins you rely on. - The file holds no secrets: a key whose name looks like a credential, or a URL with a password or token in it, is refused. Keep keys in the vault or the environment.
- Agents run as the same user as the server. On a shared machine, keep the file where that user can read it but not change it, such as a root-owned
/etc/clawboo/operator.json.
Behind a reverse proxy or on another machine
- A proxy on the same machine: leave
HOSTunset, pinCLAWBOO_API_PORT, keep the access token on (settingSTUDIO_ACCESS_TOKENgives you one you know for signing in), and setCLAWBOO_ALLOWED_HOSTSandCLAWBOO_ALLOWED_ORIGINS. Deny/api/mcp/at the proxy. - Another machine, a network or a container: set
HOST=0.0.0.0with the token on and the two allowlists. With the token turned off, the server refuses to start. - A hostname shared with other apps: serve Clawboo under a path prefix with
CLAWBOO_BASE_PATH. - A sign-in proxy for a team: have Clawboo check the proxy’s signed identity tokens, so approvals, chat and task moves record who did them. See Run Clawboo behind a sign-in proxy.
/api/mcp/ rule is required: see the advisory in the Security model.
Stop it when nobody is using it
A computer or service manager can stop Clawboo when it is idle and start it again on demand, so it does not run all day for a dashboard nobody has open. Clawboo is made for this:- It says when it is idle.
GET /api/system/idleanswers whether a person is at a dashboard (counted from the dashboard’s presence beat, never from its polling) or has taken over an agent’s screen, whether an agent run is going, and when the next routine or OpenClaw cron job is due. A stop script stops it once nobody has been there and nothing has run for a few minutes, after a drain, and starts it again a minute before the next due time. See Sleep and wake. - It starts quickly. The startup checks run SQLite’s quick integrity check in a background thread, so the server answers while they read the database; the full check runs the same way once a day, and on Re-run probe in System Health. Right after a start,
/api/healthanswers once those checks finish, while other routes,/api/system/idleamong them, answer at once. Node keeps its compiled copy of the server between starts (see Start the server directly). - It catches up once. A routine whose time passed while Clawboo was stopped runs once when it starts again; missed times are not made up. A due OpenClaw routine waits up to 5 minutes for the Gateway to connect rather than failing on it, and while it waits it counts as work, so the server is not stopped in the middle of the wait.
- It leaves an unused OpenClaw Gateway asleep. Clawboo connects to the OpenClaw Gateway only once something needs it: an OpenClaw agent, opening OpenClaw in Settings > Runtimes, or a routine for an OpenClaw agent falling due. Until then neither the server, the dashboard nor
clawbooconnects to the Gateway or probes its port, so a Gateway that a service manager starts on its first connection, such as a systemd socket unit, does not start at every boot. See How Clawboo connects.
Start it from your own app
An app can run the server as a child process of its own and show the dashboard in its own window. Startdist/server.js with an IPC channel: Node’s fork(), or spawn() with 'ipc' in its stdio.
Stop it over the channel
- With a message. Send
{ "type": "shutdown" }on the channel. The server stops as it does on Ctrl+C or SIGTERM: it stops the agent processes it started, waits up to 5 seconds for them, closes the database and exits with code0. It also stops its routines, closes its OpenClaw connection and flushes traces. From 0.9.0 the Hermes gateway gets its planned stop at the same time as that wait, and traces are flushed last, so the whole stop stays under about 11 seconds. This works on every platform, and on Windows it is the only clean stop, because a signal from another process ends the server at once there. To let the agent runs finish first, drain before you send it. - When the channel closes. Set
CLAWBOO_STOP_ON_DISCONNECT=1in the server’s environment, and it also stops this way when the channel closes: your app quit, crashed or calleddisconnect(). Without it, the server keeps running when the channel closes. Theclawboolauncher relies on that: it starts the server withfork(), lets go of the channel and exits. - A shutdown message sent while the server is still starting is kept, and the server stops once it has started. From 0.9.0 a SIGINT or SIGTERM sent while it starts is kept the same way, and a kept stop runs before anything the server starts once it listens, so no routine can start a run on a server that is stopping. Before, a SIGTERM during the start could be taken by one part of the server and lost: the server kept running, and its later stop left the OpenClaw connection open. A server that fails to start exits with code
1, whether or not your app still holds the channel. Once it is running, asking more than one way (the message, then a SIGTERM) stops it once. Other messages are ignored. - Turn off the in-app update with
CLAWBOO_DISABLE_SELF_UPDATE=1, and update the server with your app instead. The in-app update replaces the server with a new process your app did not start: it has no channel, so your app can neither stop it over one nor have it stop with the app.
CLAWBOO_STOP_ON_DISCONNECT once and removes it from its environment, so the agents and programs it starts do not inherit it, and the launcher never passes it to a server it starts.
Open the dashboard from a notification
An app that raises its own notifications can send the person from one to what it is about. Give the dashboard’s page this object, from a preload script for example:
Approvals have no page of their own: they are answered under Needs you and in the agents’ chats, so both approval targets open Needs you, as the dashboard’s own browser alerts do. Approval ids are the ones
GET /api/tools/approvals?status=pending lists. A target of any other kind is ignored. While the object is there, the dashboard’s browser alerts stay off, since your app raises its own.
Check that it is running
/api/settings answers with gatewayUrl, hasToken and firstRunDismissedAt. /api/health returns the startup checks, and "ok": true means none of the fatal ones failed. While the server moves older work into the work folder at startup, it answers "status": "migrating" instead, and other routes answer 503 until the move ends. On a token-protected install both answer 401, which also means the server is up. The System Health panel shows the same report.
Troubleshooting
CLAWBOO_API_PORT=N is already in use.
CLAWBOO_API_PORT=N is already in use.
A pinned port gets no fallback. Free that port, choose another, or unset
CLAWBOO_API_PORT so the server picks a free one.Dashboard is taking too long to start.
Dashboard is taking too long to start.
The launcher waited 45 seconds without an answer. It prints the last lines of
~/.clawboo/server.log and the log’s path: read them for the cause. On 0.5.0 and older, if you set STUDIO_ACCESS_TOKEN, the server may be running fine, because those launchers cannot see past the token. Open the dashboard with ?access_token=<your-token>. Newer launchers use the token from the shell and see the server answer.A Clawboo server is running on port N, but it requires an access token.
A Clawboo server is running on port N, but it requires an access token.
The server was started with a
STUDIO_ACCESS_TOKEN that the shell you ran the command in does not have. Set STUDIO_ACCESS_TOKEN to that token and run the command again. To open the dashboard, open the address the message prints, with your token in place of <token>. Without the token, stop the server with Ctrl+C in its terminal, with your service manager, or with the command clawboo stop prints.Clawboo requires Node.js 22.12 or newer
Clawboo requires Node.js 22.12 or newer
Install a current Node from nodejs.org, or switch with a version manager (
nvm install 22, fnm use 22), then run clawboo again.Page loads answer 503: The Clawboo dashboard could not be read from disk.
Page loads answer 503: The Clawboo dashboard could not be read from disk.
CLAWBOO_UI_DIR does not point at the dashboard files. Unset it to use the ui folder that ships next to server.js.Could not find the Clawboo server.
Could not find the Clawboo server.
The launcher cannot find
server.js next to itself. Reinstall with npm install -g clawboo.SECURITY: refusing to start
SECURITY: refusing to start
HOST is set to a network address and the access token is turned off (STUDIO_ACCESS_TOKEN= set blank). See Reach Clawboo from another machine, or unset HOST to listen on 127.0.0.1 only. If the message names ~/.clawboo/access-token, the token file is not one Clawboo can trust: delete it, and the next start makes a new one. If the message names an unsupported character in STUDIO_ACCESS_TOKEN, the token has a character other than letters, digits, ., _, ~ and -, which stops the server on any address: replace it with one from openssl rand -hex 24.SECURITY/CONFIG: CLAWBOO_BASE_PATH is invalid
SECURITY/CONFIG: CLAWBOO_BASE_PATH is invalid
The message names the problem with the value. Use a prefix like
/clawboo, or unset the variable to serve at the root.Related
- Reach Clawboo from another machine: SSH tunnels, reverse proxies, network binds and path prefixes
- Security model: what is protected by default, and where your keys are stored
clawbooCLI reference: every command, port discovery, stop and restart- Data and state: every file in your Clawboo folder, backups and resets
- Environment variables: every setting the server reads
- Limits and defaults: ports, timeouts, rate limits and other numbers