Skip to main content
Clawboo runs as one server process. On one port it serves the dashboard, its API and a WebSocket for the OpenClaw Gateway. Use this page to start that server, keep it running as a service, update it and find its logs. To open the dashboard from another computer, see Reach Clawboo from another machine.

Before you begin

  • Node.js 22.12 or newer. The clawboo command 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

The launcher does three things:
  1. 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: -y restarts without asking, and --no-version-check skips the check.
  2. 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.
  3. It waits up to 45 seconds for the server to answer, then opens http://127.0.0.1:<port>/ (plus your CLAWBOO_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.
The server keeps running after the launcher exits. 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=production gives 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/teams by default.
  • The dashboard files come from the ui folder next to server.js. CLAWBOO_UI_DIR points somewhere else. If Clawboo cannot read index.html there, page loads answer 503 with “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/config name the bundled MCP programs, also set CLAWBOO_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-token of the user account it runs as. Run clawboo open as that user to open a signed-in browser, or clawboo open --print for 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:
Replace the two paths in 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:
Generate the token with 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_USER runs the server and CLAWBOO_AGENT_USER runs 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 /data and /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.
Set it up in a container covers what the launcher does step by step. On a computer or virtual machine, use the sudo setup that 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 to server.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_LEVEL sets how much the server logs: info by default, debug for more.
  • After an in-app update, the new server’s output does not reach server.log. Run clawboo restart to capture it again.

Update Clawboo

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.
To find updates, the server asks 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 restart after 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 a CLAWBOO_OPERATOR_SETTINGS that 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.
Environment variables has each key’s details.

Behind a reverse proxy or on another machine

  • A proxy on the same machine: leave HOST unset, pin CLAWBOO_API_PORT, keep the access token on (setting STUDIO_ACCESS_TOKEN gives you one you know for signing in), and set CLAWBOO_ALLOWED_HOSTS and CLAWBOO_ALLOWED_ORIGINS. Deny /api/mcp/ at the proxy.
  • Another machine, a network or a container: set HOST=0.0.0.0 with 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.
Reach Clawboo from another machine has the steps and the nginx, Caddy and Cloudflare Tunnel configs. On Clawboo 0.5.0 and older the /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/idle answers 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/health answers once those checks finish, while other routes, /api/system/idle among 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 clawboo connects 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. Start dist/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 code 0. 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=1 in the server’s environment, and it also stops this way when the channel closes: your app quit, crashed or called disconnect(). Without it, the server keeps running when the channel closes. The clawboo launcher relies on that: it starts the server with fork(), 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.
The server reads 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:
The dashboard subscribes once, when it loads, and opens: 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

Use the port from the first command. /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

A pinned port gets no fallback. Free that port, choose another, or unset CLAWBOO_API_PORT so the server picks a free one.
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.
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.
Install a current Node from nodejs.org, or switch with a version manager (nvm install 22, fnm use 22), then run clawboo again.
CLAWBOO_UI_DIR does not point at the dashboard files. Unset it to use the ui folder that ships next to server.js.
The launcher cannot find server.js next to itself. Reinstall with npm install -g clawboo.
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.
The message names the problem with the value. Use a prefix like /clawboo, or unset the variable to serve at the root.
Last modified on November 18, 2026