- nginx
- Caddy
- Cloudflare Tunnel
/API/MCP/config. Under a path prefix, add the same rule for the prefixed path (/clawboo/api/mcp), because Clawboo also answers /api/ without the prefix. Releases after 0.5.0 require the access cookie on these paths. The four MCP server paths also accept an agent’s attach token, but /api/mcp/config never does, and an attach token that arrives through a proxy is refused. The proxy recipes below keep the rule as a second layer.
Choose a path
~/.clawboo/access-token unless you set STUDIO_ACCESS_TOKEN yourself, and anyone who has it, or a live one-time sign-in link, can do everything you can. Keep both to yourself.
Before you begin
- Clawboo is installed on the server with
npm install -g clawboo(Install Clawboo). - You know the server’s Clawboo port. While Clawboo runs,
cat ~/.clawboo/api-port.txtprints it; it is usually18790. - You know your version: run
clawboo --version. On 0.5.0 or older, read the advisory above first.
Option 1: SSH tunnel (recommended)
The tunnel forwards a port on your computer to Clawboo’s port on the server. Clawboo keeps listening only on the server itself, and SSH does the authentication.Start Clawboo on the server
clawboo on the server as usual, with HOST unset. On a server without a desktop the browser does not open; that is fine.Open the tunnel from your computer
http://localhost:<local-port> to CLAWBOO_ALLOWED_ORIGINS).Sign in through the tunnel
clawboo open --print. It prints a one-time sign-in link such as http://127.0.0.1:18790/?access_code=…. Open that link on your computer within two minutes. You should see your dashboard, and this browser stays signed in. The tunnel stays open until you stop the ssh command.Option 2: Reverse proxy
A reverse proxy such as nginx, Caddy or a Cloudflare Tunnel gives Clawboo a web address with HTTPS. The proxy runs on the same machine, and Clawboo keeps listening only on127.0.0.1.
Create an access token and save it
., _, ~ and -. With any other character the server refuses to start. Without this step the server would use its per-install token from ~/.clawboo/access-token, which works too but is harder to sign in with from another computer.Start Clawboo with the token and your address
dash.example.com with your own:HOST unset, because the proxy connects to 127.0.0.1. CLAWBOO_API_PORT pins the port the proxy forwards to. The two allowlist variables let requests that use your address pass Clawboo’s same-origin guard. Without them the dashboard page loads, but every API call fails with 403 Cross-origin request blocked.This starts the server in this terminal, and you should see a log line saying Clawboo is ready. clawboo works too: run in this shell, it passes these variables to the server it starts, and with the token set there clawboo stop and clawboo restart can stop and restart that server. To keep it running after you log out, run it as a service.Point the proxy at Clawboo
- nginx
- Caddy
- Cloudflare Tunnel
Host your browser used and X-Forwarded-Proto. Clawboo checks Host against the allowlist, builds the redirect after sign-in from both, accepts a sign-in form only when its Origin matches both, and marks the cookie Secure when X-Forwarded-Proto is https.Sign in once
https://dash.example.com/?access_token=<your-token>. Clawboo sets a cookie and removes the token from the address bar, and you should see your dashboard. Each browser signs in once. The token appears in that first request’s URL, so a proxy access log can record it; keep such logs private. To sign in a phone or another browser after that, use Open on another device at the bottom of the sidebar: its one-time link and QR code carry a code that works once, within two minutes, never the token. An app added to a phone’s home screen signs in by pasting that link on its locked screen (see Paste a sign-in link).SECURITY: warning on the first proxied request. That is expected. If the proxy runs on a different machine, Clawboo must listen on the network. Use the bind and token from Option 3, point the proxy at the server’s address, and keep the allowlists set to your public name.
Option 3: Network bind
A network bind makes Clawboo listen on every interface of the machine, so other computers on the network can open it directly. Use it on a network you trust, or for a container whose port you publish.Create an access token and save it
openssl rand -hex 24 and save the token, as in Option 2. Clawboo refuses to start on a network bind without a working token. Without one of your own it uses its per-install token: to sign in with that, run clawboo open --print on the server and open the link it prints with 127.0.0.1 replaced by the server’s address, within two minutes.Start Clawboo on all interfaces
192.168.1.10 with the server’s address on your network:HOST=0.0.0.0, not the server’s own address. Clawboo’s agents and background jobs connect to 127.0.0.1, and a bind to one address does not listen there, so agents would lose their Clawboo tools. In a container, HOST=0.0.0.0 is also what lets the published port reach the server.Sign in once
http://192.168.1.10:18790/?access_token=<your-token>. You should see your dashboard. Once one browser is signed in, Open on another device at the bottom of the sidebar shows a one-time link and a QR code for a phone on the same network.http:// sends the cookie unencrypted, so anyone who can watch the network can copy it and use the dashboard. For anything beyond a network you trust, put a TLS proxy in front (Option 2).
Serve Clawboo under a path prefix
To share one hostname with other apps, serve Clawboo under a prefix such as/clawboo. Add CLAWBOO_BASE_PATH to the variables from Option 2; the allowlists name the shared host:
proxy_pass with no path after the port:
https://apps.example.com/clawboo/?access_token=<your-token>.
Under a prefix, the dashboard, the API, the live streams and the Gateway WebSocket all live below it, and the prebuilt package needs no rebuild. The access cookie’s path is the prefix, so other apps on the same host never receive it, and the dashboard’s own browser storage is kept per prefix, so two Clawboo instances on one hostname keep separate themes, layouts and onboarding progress. The value may use only letters, digits, ., _, ~ and - between slashes, and its first part must not be api. An invalid value stops the server at startup with SECURITY/CONFIG: CLAWBOO_BASE_PATH is invalid.
Put the dashboard on your phone
The dashboard installs as a web app: it opens from your phone’s home screen in a window of its own, with no address bar. A phone’s browser installs it only from a secure address:https://, or http://localhost and http://127.0.0.1 on the phone itself, as through an SSH tunnel that runs on the phone. For any other address, set up Option 2: Reverse proxy first; it works under a path prefix too. Over a plain http:// network address, such as a network bind, the dashboard opens in the phone’s browser, but the browser does not offer to install it.
Sign in your phone
Add it to your home screen
- Android, in Chrome: open the browser menu and tap Install app or Add to Home screen.
- iPhone and iPad, in Safari: tap the share button, then Add to Home Screen.
- It signs in the way the browser does. The installed app uses the same access cookie. Installing it puts the token in no address and stores no copy of it.
- Android shares the sign-in with Chrome. An app installed from Chrome uses Chrome’s cookies.
- iPhone and iPad keep it apart. iOS gives a home-screen app storage of its own, apart from Safari’s, and a sign-in link you tap opens in Safari rather than in the app, so the installed app can open on the locked screen, or lose its sign-in later. Sign it in there with the Paste a sign-in link box: in a signed-in browser, open Open on another device at the dashboard’s address the phone uses, click Copy link, send the link to the phone, and paste it into the box within two minutes. See The access token.
- No offline copy. Clawboo ships no service worker. The installed app shows only live data, needs the server to be reachable, and keeps nothing from the API for offline use.
Check that it worked
From another computer, run these with your own address in place ofdash.example.com:
/api/settingsshould answer401: Clawboo is reachable and wants the token. A403meansCLAWBOO_ALLOWED_HOSTSdoes not include the name you used. A200means a request with no credentials got through, so anyone who can reach this address can use Clawboo: the token is turned off, so remove the blankSTUDIO_ACCESS_TOKEN=or set a token.- The two
/api/mcp/addresses should answer404from your proxy. A401means Clawboo refused them but your deny rule is missing. A200or400means they reached Clawboo’s MCP endpoints: add the deny rule now.
Settings at a glance
Troubleshooting
Every action fails with 403 Cross-origin request blocked.
Every action fails with 403 Cross-origin request blocked.
CLAWBOO_ALLOWED_HOSTS to the host name and CLAWBOO_ALLOWED_ORIGINS to the full origin (scheme, host, and the port if it is not the default), then restart. Through an SSH tunnel, use the same port on both ends.The dashboard says it could not tell this came from you
The dashboard says it could not tell this came from you
403 person_only, and moving a card does not stop its run. Clawboo reads the marks a browser puts on the dashboard’s requests, and something in between changed them. Over plain http to another machine’s address, a browser sends only Origin, and it has to match the Host Clawboo receives. A proxy that rewrites Host, as nginx does by default, breaks that. Add proxy_set_header Host $host;, or serve Clawboo over https, where a browser sends the marks a proxy leaves alone. See the person check.The dashboard says it is not signed in through your sign-in proxy
The dashboard says it is not signed in through your sign-in proxy
proxyIdentity: on and personCheck: verified, only a request your sign-in proxy signed acts as you. A dashboard opened around the proxy, such as at http://localhost:18790 or the server’s own address, sends no token: it can show your agents, but answering approvals and taking over a screen are refused with 403 person_only, a card you move there moves without stopping its run, and the Gateway connection is refused. With proxyIdentity: required, the page loads but shows none of your data: its API requests carry no token, so they are refused with 401 and “Clawboo needs a signed identity token from your sign-in proxy for this request.” Open Clawboo at the address your proxy serves. If you do and still see it, check that the proxy sends its token on every request, GET /api/access/identity included. See Only signed requests act as a person.401: Clawboo access token required
401: Clawboo access token required
?access_token=<your-token> once, or open a one-time link from clawboo open --print on the server (replace 127.0.0.1:<port> with the address you use) or from Open on another device in a signed-in browser.401: Invalid Clawboo access token.
401: Invalid Clawboo access token.
STUDIO_ACCESS_TOKEN the server started with. Check for missing or extra characters.After signing in, the browser goes to an http address or to 127.0.0.1
After signing in, the browser goes to an http address or to 127.0.0.1
Host and X-Forwarded-Proto it receives. Make the proxy pass both; in nginx, proxy_set_header Host $host; and proxy_set_header X-Forwarded-Proto $scheme;.The boot log says STUDIO_ACCESS_TOKEN contains an unsupported character
The boot log says STUDIO_ACCESS_TOKEN contains an unsupported character
., _, ~ and -, so the server stopped rather than run without the token check. Make a new token with openssl rand -hex 24, start the server with it, and sign in again.The log says a request reached this server through a reverse proxy
The log says a request reached this server through a reverse proxy
STUDIO_ACCESS_TOKEN= set blank), so the dashboard and every /api/ route are open to anyone who can reach the proxy. Set a token, or unset the variable to use the per-install one, and restart, unless the proxy authenticates every request. The warning appears once per server start and never blocks a request.clawboo says a server is running but requires an access token
clawboo says a server is running but requires an access token
clawboo, clawboo stop and clawboo restart cannot use its API. Set STUDIO_ACCESS_TOKEN to the server’s token in that shell and run the command again. Otherwise stop the server with Ctrl+C in its terminal, with your service manager, or with the command clawboo stop prints.The server exits with SECURITY: refusing to start
The server exits with SECURITY: refusing to start
HOST is a network address and the access token is turned off (STUDIO_ACCESS_TOKEN= set blank). Set a token (letters, digits, ., _, ~ and - only) or unset the variable to use the per-install one, or unset HOST to listen on 127.0.0.1 again. A token file Clawboo cannot use also stops it with this message, naming the file: delete the file to get a new one. If the message names an unsupported character in STUDIO_ACCESS_TOKEN, see the entry above.Agents lost their Clawboo tools after setting HOST
Agents lost their Clawboo tools after setting HOST
HOST names a single address, so Clawboo no longer listens on 127.0.0.1, where its agents connect. Use HOST=0.0.0.0 instead.Live updates stop, or long requests are cut off, behind nginx
Live updates stop, or long requests are cut off, behind nginx
proxy_buffering off; and a longer proxy_read_timeout, as in the recipe above.MCP attach config shows Could not load attach config.
MCP attach config shows Could not load attach config.
/api/mcp/config, which your proxy now denies. That is expected. Open the dashboard through an SSH tunnel when you need it.An agent on another computer cannot attach to the MCP servers
An agent on another computer cannot attach to the MCP servers
Limits
- One token, full access. There are no accounts or roles. To rotate the token, change the variable, restart the server and sign in again in every browser. Behind a sign-in proxy, each person can have a role that decides what they may do.
- One rate-limit allowance behind a proxy. Clawboo counts requests by the connection’s address, so every browser behind the proxy shares one allowance. See Limits and defaults.
Next steps
- Security model: what each protection covers, and where your keys are stored
- Run the Clawboo server: run it as a service, update it and read its logs
- MCP servers: attach agents from other tools to Clawboo
- Data and state: back up and move your Clawboo folder
- Environment variables: every setting the server reads