Skip to main content
Clawboo listens only on the computer it runs on. Use this guide to open the dashboard from somewhere else: your laptop reaching a home server or a VPS, or another computer on your network. Each path below keeps the dashboard private to you. For why each step matters, see the Security model.
Security advisory: clawboo 0.5.0 and older behind a reverse proxy. On these releases the access token does not cover /api/mcp/. Any request that reaches Clawboo from 127.0.0.1 skips the access cookie on every /api/mcp/ path, including /api/mcp/config. A reverse proxy on the same machine delivers every request from 127.0.0.1. So anyone who can reach your proxy can use Clawboo’s MCP servers and ask /api/mcp/config for an attach URL signed as any of your agents, with that agent’s connector grants. This holds even with STUDIO_ACCESS_TOKEN set.If you already run Clawboo behind nginx, Caddy or a Cloudflare Tunnel, add the rule below for your proxy now, or upgrade to 0.6.0. Run clawboo --version to see your version.
The rules ignore letter case, because 0.5.0 also routes variants such as /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 has no user accounts. Every install has an access token, kept in ~/.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.txt prints it; it is usually 18790.
  • You know your version: run clawboo --version. On 0.5.0 or older, read the advisory above first.
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.
1

Start Clawboo on the server

Run clawboo on the server as usual, with HOST unset. On a server without a desktop the browser does not open; that is fine.
2

Open the tunnel from your computer

Use the server’s Clawboo port on both sides. With a different local port, your browser’s address no longer matches Clawboo’s port, and Clawboo blocks the dashboard’s requests (unless you add http://localhost:<local-port> to CLAWBOO_ALLOWED_ORIGINS).
3

Sign in through the tunnel

On the server, run 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.
The tunnel needs no token of your own. Anyone else who can log in to the server can reach Clawboo’s port too, but the server’s per-install token, readable only by your account there, keeps them out of the API.

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 on 127.0.0.1.
1

Create an access token and save it

This prints a 48-character token. Save it in your password manager now: you need it to sign in, and the server must start with the same value every time. If you write your own token, use only letters, digits, ., _, ~ 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.
2

Start Clawboo with the token and your address

Replace the token and dash.example.com with your own:
Leave 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.
3

Point the proxy at Clawboo

Whatever the proxy, it must pass the 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.
4

Sign in once

Open 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).
A reverse proxy is not authentication. The proxy delivers every request from 127.0.0.1, so to Clawboo the whole internet looks like a local caller. With the token turned off (STUDIO_ACCESS_TOKEN= set blank), or on 0.5.0 and older without STUDIO_ACCESS_TOKEN, the dashboard and every /api/ route are open to anyone who can reach the proxy, and the server starts without complaint. Keep the token unless the proxy authenticates every request itself (HTTP basic auth, an SSO proxy such as oauth2-proxy, Cloudflare Access).
If your proxy does authenticate every request and you leave the token out, Clawboo logs a one-time 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.
1

Create an access token and save it

Run 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.
2

Start Clawboo on all interfaces

Replace the token and 192.168.1.10 with the server’s address on your network:
Use 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.
3

Sign in once

On the other computer, open 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.
Plain 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:
The proxy must pass the prefix through unchanged. In nginx, that means a proxy_pass with no path after the port:
With a trailing slash after the port, nginx strips the prefix, Clawboo redirects the page back to the prefix, and the browser loops until it gives up. Sign in at 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.
1

Sign in your phone

On your computer, open the dashboard and click Open on another device at the bottom of the sidebar. Scan its QR code with your phone’s camera. The link signs in the phone’s browser and carries a one-time code that works once, within two minutes, never the access token.
2

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.
The installed app opens at the dashboard’s address, under your prefix if you serve Clawboo under one.
  • 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.
Where things live lists what the dashboard lays out for a phone’s width.

Check that it worked

From another computer, run these with your own address in place of dash.example.com:
  • /api/settings should answer 401: Clawboo is reachable and wants the token. A 403 means CLAWBOO_ALLOWED_HOSTS does not include the name you used. A 200 means 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 blank STUDIO_ACCESS_TOKEN= or set a token.
  • The two /api/mcp/ addresses should answer 404 from your proxy. A 401 means Clawboo refused them but your deny rule is missing. A 200 or 400 means they reached Clawboo’s MCP endpoints: add the deny rule now.
Then sign in with your browser, open the board and send a message in a team chat. If both work, the allowlists are right.

Settings at a glance

Environment variables lists every setting.

Troubleshooting

Clawboo’s same-origin guard does not recognize the name or origin in the request. Set 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.
Answering an approval, Retry, Assign and a team’s work check are refused with 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.
From 0.9.0, with 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.
This browser has no cookie yet, or the token changed. Open your Clawboo address with ?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.
The token in the URL does not match the STUDIO_ACCESS_TOKEN the server started with. Check for missing or extra characters.
Clawboo builds the redirect from the 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 token has a character other than letters, digits, ., _, ~ 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 server’s access token is turned off (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.
The shell you ran the command in does not have the server’s token, so 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.
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.
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.
By default nginx buffers responses and closes a connection after 60 seconds without data. Add proxy_buffering off; and a longer proxy_read_timeout, as in the recipe above.
That section, on the OpenClaw row under Settings then Runtimes, reads /api/mcp/config, which your proxy now denies. That is expected. Open the dashboard through an SSH tunnel when you need it.
The proxy rule blocks it, and releases after 0.5.0 also refuse an attach token that arrives through a proxy. Give that computer an SSH tunnel to the server’s Clawboo port instead; see 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

Last modified on November 18, 2026