~/.clawboo, and its agents’ work in another, the work folder (~/clawboo-work). The runtimes it installs for you go in a third, the runtimes folder (~/clawboo-runtimes). It also writes a few files in OpenClaw’s folder, ~/.openclaw, and a reset of ~/.clawboo leaves those alone.
Where Clawboo keeps its data
Clawboo’s data folder is~/.clawboo. To use another folder, set CLAWBOO_HOME before you start the server (a leading ~ is expanded). The database, the key vault, the settings and the logs move with it. The work folder becomes <CLAWBOO_HOME>-work unless CLAWBOO_WORK_DIR names another, and the runtimes folder becomes <CLAWBOO_HOME>-runtimes unless CLAWBOO_RUNTIMES_DIR names another. Team folders, task checkouts and review checkouts live in the work folder; see The work folder. OpenClaw, Claude Code’s Agent SDK, Codex and Hermes, when Clawboo installs them, live in the runtimes folder; see The runtimes folder.
On macOS and Linux, Clawboo makes the database, its working files,
settings.json and the folder readable only by your user account, and keeps secrets/ the same way. A server started by clawboo also uses this folder as its working directory. A coding agent that runs without a worktree (every team-chat turn, every one-to-one chat, research and review tasks, and Routines you make in the dashboard) starts in the work folder instead: in the task’s own folder on a run that holds a task, else in its team’s folder. It still has your account’s full file access, unless CLAWBOO_AGENT_USER runs it as its own user; see What agents can do.
The work folder
Your agents’ work lives in the work folder, apart from the data folder. It is the folderCLAWBOO_WORK_DIR names, else <CLAWBOO_HOME>-work when CLAWBOO_HOME is set, else ~/clawboo-work (%USERPROFILE%\clawboo-work on Windows). Clawboo uses it by its real path, with every link resolved.
Everything Clawboo creates in the work folder is readable only by your user account (
0700), or only by the agent user with CLAWBOO_AGENT_USER set. The .<task id>.owner file beside each checkout holds this install’s id. The worktree cleanup in the work folder removes only checkouts this install’s board records or that carry its id, so two installs can share one work folder.
The data folder keeps the rest: the database, the key vault, the settings, the runtime homes (runtimes/), the browser profiles, connector state, and team-folder-history/, the work check’s history of each team folder. With CLAWBOO_AGENT_USER set, the work folder, the runtime homes and the browser profiles are in the agent user’s home instead; see With agents as their own user.
Keeping the work apart removes the short relative path from an agent’s folder to your data: ../.. from a team folder no longer reaches the database, and neither does a tool that walks up parent folders. That holds only for work in the work folder. When the work folder cannot be created and the install keeps the old layout, or the move below keeps a folder at its old place, that folder is still inside the data folder and ../.. from it does reach the data. It is not a boundary either way. Agents still run as your user account and can open ~/.clawboo by its full path; see What agents can do. With CLAWBOO_AGENT_USER set, agents run as a user that cannot open the database, the vault, its key, settings or the token at all.
Task folders
A task that a Claude Code, Codex, Hermes or Clawboo Native agent runs without a worktree gets a folder of its own,teams/<team id>/tasks/<task id>, or teams/_no-team/tasks/<task id> for a task with no team. That covers tasks handed out in team chat, tasks you give from the Board, tasks a routine files, and research and review runs of the task runner. Each run on the task starts there and is told to save the files it makes for the task there, and that the team’s shared folder is two levels up (../..), where tasks/ holds the other tasks’ folders. Clawboo creates the folder, readable only by your user account (or only by the agent user with CLAWBOO_AGENT_USER set), on the task’s first run. A turn that holds no task, such as the lead’s turn or your message in team chat, still starts in the team’s folder. OpenClaw agents work in their Gateway’s own workspace and get no task folder.
The task folders sit inside the team’s folder on purpose: the team’s work check measures the team’s folder, so a change in a task folder counts, and deleting a team deletes its task folders with it. Archiving a team keeps them.
When the server starts, Clawboo removes the empty folders of finished tasks:
- Only empty folders. The remove is plain and not recursive, so a folder that holds any file is kept. Unlike a worktree, a task folder has no branch that keeps its work, so its files stay until you delete them or delete the team.
- Only finished tasks. A task that is Done, Cancelled or dropped loses its empty folder. A task that is still going or could still run (To do, Blocked, In progress or In review) keeps it.
- Only this install’s tasks. The cleanup looks in the folders of this install’s teams and
_no-team, and leaves alone a folder whose name is not one of this install’s tasks, so a work folder two installs share is safe. - Links are never followed. A
tasks/folder that is a link is skipped, and a link inside it is left as it is. - As the agent user, with
CLAWBOO_AGENT_USERset. Every look, listing and removal goes through the agent host, so Clawboo never removes anything in the agents’ folders as your user.
Move older work into it
Older versions kept team folders in~/.clawboo/workspaces and task checkouts in ~/.clawboo/worktrees. Once per start, after the database opens and stale runs are released, and before the worktree cleanup or any run, Clawboo moves the team folders it finds in workspaces/, and the checkouts the board records in worktrees/, into the work folder:
- Renames only. Nothing is copied, so a folder usually takes milliseconds.
- A link at each old path.
~/.clawboo/workspaces/<team id>still leads to the folder, for older versions and for tools that saved the path. - Uncommitted work is saved first. Before a checkout moves, Clawboo commits its uncommitted work on the task’s branch (
clawboo: save work before moving task <id>), the same kind of commit a pause makes. The checkout moves withgit worktree move, or, when it is locked, with a rename andgit worktree repair, which needs git 2.30 or later. The board’s recorded paths change to the new place. - Paused tasks move too. A paused task’s record names the new place, and resuming the task rebuilds its checkout in the work folder.
- Review checkouts stay. Clawboo does not move them. New ones go in the work folder, in
reviews/under a folder named for this install, since two installs that share a work folder can review the same commit. - A crash is safe. Every step is written to a journal before it happens, so a crash or a kill at any point is finished or undone at the next start. When a folder has moved but the link at its old path cannot be made, the move still counts: runs use the new path, and the journal notes the missing link.
- One server moves at a time. A second server started on the same data folder waits for the first one’s move to end, answering
migratingmeanwhile, and then starts.
CLAWBOO_AGENT_USER set, the move does not run. The work folder belongs to the agent user, so Clawboo copies older work into it instead; see With agents as their own user.
What the move leaves where it is
The move leaves these where they are, logs the warningWork folder: kept at its old place, and tries again at the next start. Each one keeps working where it is:
- a folder on another volume, since the move never copies;
- a checkout git does not list;
- a checkout with a run still going in it;
- a conflict, where something is already at the new path. Both are kept, and the team keeps using its old folder.
Change the work folder
Stop Clawboo, setCLAWBOO_WORK_DIR to the new folder, and start it again. Clawboo treats the change as a move: at that start, this install’s team folders and recorded checkouts move from the previous work folder to the new one, with links left at the previous paths. The same rules apply, so work on another volume stays in the previous folder and keeps working there. A previous work folder that is not there at that start, such as one on a drive that is not mounted, stays on record with the warning Work folder: the previous work folder is not there, and its team folders move at the first start that finds it again. Changing back to a work folder used before works the same way: the links the earlier move left there are replaced by the folders.
While the move runs
The server listens while it moves folders, so a service manager or a monitor sees it starting:GET /api/healthanswers200with{ "ok": false, "status": "migrating", "migration": { "total": 4, "done": 1, "left": 3 } }.- Every other request answers
503withRetry-After: 2and{ "error": "Clawboo is moving its work folders. Try again in a moment.", "status": "migrating" }. - A WebSocket connection is refused with
503.
When Clawboo refuses to start
The server exits at startup when the work folder is the data folder, sits inside it, or contains it. It compares real paths, so a link cannot hide one folder inside the other:Clawboo's data folder (<path>) must be outside the work folder (<path>). Set CLAWBOO_WORK_DIR to a folder that does not contain it. The server also refuses to start when it cannot create or write to a CLAWBOO_WORK_DIR you set (CLAWBOO_WORK_DIR (<path>) cannot be used: <reason>), and when teams/, worktrees/ or reviews/ inside the work folder is a link (<path> is a link. Clawboo puts agents' work only in a real folder there: remove the link and start again.) or a file (<path> is not a folder.). On Windows and macOS the comparison ignores case, since their file systems usually do.
When the work folder cannot be created
WhenCLAWBOO_WORK_DIR is not set and Clawboo cannot create or write to the default work folder, as in a container whose data folder is a volume under a root-owned /, it logs a warning and keeps the old layout: new work stays in the data folder (workspaces/, worktrees/ and reviews/), and nothing moves. Set CLAWBOO_WORK_DIR to a folder Clawboo can create, such as a second volume in a container, and the next start moves the work there.
Roll back to 0.6.x
You can go back to 0.6.x after the move. 0.6.0 already reads checkouts in the work folder, and finds team folders through the links. One limit: 0.6.x’s work check refuses a team folder in the work folder, so team chat work checks fail on 0.6.x until you upgrade again. Versions before 0.6.0 do not read the work folder, so do not go below 0.6.0 after the move.With agents as their own user
WithCLAWBOO_AGENT_USER set, agents run as a separate user, and their folders belong to it, in its home folder. With the commands clawboo agent-user plan prints, that home is /var/lib/clawboo-agent on Linux and /var/clawboo-agent on macOS.
The move above does not run, since Clawboo cannot write in the agent user’s folders as you. Instead, the first start with the setting copies what agents already had into the agent user’s space: each runtime home (Hermes memory and skills, Codex sessions) and each team folder, from the data folder’s
workspaces/ and from the work folder used before. It never copies a link, a file with more than one hard link, a sign-in or key file (auth.json, .env: before, those were copies of your own logins and keys) or Clawboo Native’s history, and names what it skipped in the log. Task checkouts are not copied: they are rebuilt in the new work folder from their branches. The originals stay where they were, so turning the setting off again is the way back.
With the setting on, Clawboo never falls back to the old layout: the agent user must be able to write in its work folder, or Clawboo refuses to start (see What the startup check proves).
A user per agent (CLAWBOO_AGENT_USERS, Linux only for now) lays this out differently: the work folder is the one CLAWBOO_WORK_DIR names and is yours, each agent’s runtime homes and browser profile are under its own user’s home, and nothing older is copied in.
The runtimes folder
The runtimes Clawboo installs for you (OpenClaw, Claude Code’s Agent SDK, Codex and Hermes) live in the runtimes folder, never in npm’s global folder. It is the folderCLAWBOO_RUNTIMES_DIR names (a leading ~ is expanded), else <CLAWBOO_HOME>-runtimes when CLAWBOO_HOME is set, else ~/clawboo-runtimes (%USERPROFILE%\clawboo-runtimes on Windows). Clawboo uses it by its real path, with every link resolved, and creates it on the first install.
This is not the
runtimes/ folder inside ~/.clawboo. That one holds each Codex and Hermes agent’s own home, with its sessions and sign-in copy.How an install works
OpenClaw, Claude Code and Codex install the same way, whether from Install in Settings > Runtimes, Set up OpenClaw, or Check for Updates in Settings > System:- npm runs on the Node.js Clawboo runs on. Clawboo runs npm’s own script with that Node: the npm that ships beside it, Homebrew’s npm for a Homebrew Node, or the
npmon yourPATH. Only when it cannot find that script does it run thenpmcommand itself, with that Node’s folder first onPATH. - Each install goes into a new folder. The command is
npm install --prefix <new install folder> --include=optional --no-global --location=project --no-fund --no-audit <spec>. It runs under umask 022, and withoutnpm_config_global,npm_config_locationandnpm_config_prefixin its environment, so neither your environment nor an.npmrcwithglobal=truemakes it write to npm’s global folder, and it never needssudo. - Success switches to it. Clawboo writes the launchers in
bin/and pointsclawboo-runtime.jsonat the new install, all or nothing. It keeps the previous install, and any install a Gateway it started is still running from, and removes older ones. - Failure changes nothing. When npm fails, or the install is stopped, Clawboo removes the new folder and the current install stays as it was. A failed update never leaves a runtime half replaced. The error carries npm’s own code, such as
EACCESorETARGET, and the message readsInstallation failed with exit code <n>.followed by npm’s reason.
0755. Before an install becomes current, Clawboo makes everything in it readable by other users and writable only by the server’s user, so another account on the computer can run a runtime but cannot change it. An install fails when an item in it belongs to another user, or when a link inside it points outside the install.
Which copy Clawboo uses
Wherever Clawboo looks for a runtime, it looks in the runtimes folder first, then on yourPATH, then in the usual user-install folders. That covers OpenClaw detection, the Gateway Clawboo starts, the openclaw commands it runs, Codex runs and the Runtimes panel. Hermes is the exception: Clawboo runs only its own install of Hermes. So an OpenClaw or Codex you installed globally yourself keeps working while Clawboo has no copy of its own. A Claude Code run loads the Agent SDK from the runtimes folder first, else from next to Clawboo: a source checkout’s node_modules, or an SDK installed next to a global Clawboo.
The runtimes folder is not on your PATH. To run a runtime Clawboo installed from your own terminal, use its launcher’s full path, such as ~/clawboo-runtimes/bin/openclaw doctor --fix. Where the dashboard shows a command for you to run, such as a sign-in, it already names that full path.
For a Homebrew Node.js from a formula held to one major version, such as node@24, a launcher names the formula’s link, such as /opt/homebrew/opt/node@24/bin/node, rather than the versioned folder an upgrade deletes, so brew upgrade keeps it working on that major version. The node formula’s link moves to each new major version on brew upgrade, so from 0.9.0 a launcher for that formula names its versioned folder instead, and a runtime never runs on a major version it was not installed for. After an upgrade within the same major version, Clawboo moves the runtime to the new version once Clawboo runs on it (see below). In 0.8.0 and before, a launcher named the node formula’s link too, so a runtime installed that way runs on whatever version that link leads to: install it again after a brew upgrade to a new major version. If the Node.js a launcher names is removed, for example by nvm uninstall or a Homebrew upgrade, Clawboo stops using that launcher. The runtime reads Not installed unless a global copy exists, the Runtimes panel and GET /api/system/status say why (Clawboo's copy of <runtime> runs on <path>, which is gone or can be changed by another user), and Install puts it back on the Node.js Clawboo runs on now.
From 0.9.0, Clawboo moves the runtime to the Node.js it runs on instead, when nothing is left at the recorded path and the Node.js Clawboo runs on is the same version as the one that installed it, or a later release of the same major version (Node.js 24.15 to 24.16, never 24 to 25, never back to an older release), on the same kind of processor (arm64 or x64, since npm picked the runtime’s native parts for it; installs from 0.8.0 and before did not record it, so for those this is not checked, and you should install such a runtime again if Clawboo now runs on a Node.js for another kind of processor). That covers an app that runs Clawboo on a Node.js of its own being moved or renamed, an nvm uninstall of the release Clawboo no longer runs on, and a brew upgrade of the node formula within a major version. A runtime with no launcher, such as Claude Code’s Agent SDK, is loaded by the server rather than started on that Node.js, and is left as it is. At startup, and whenever it looks for that runtime, Clawboo rewrites the runtime’s launchers and clawboo-runtime.json to name the Node.js it runs on, by the same kind of path a new install records. The install, its version and its install time stay as they were. The launchers go first and clawboo-runtime.json last: a failure puts every launcher back, and a server stopped part way leaves the old clawboo-runtime.json, so the next start finishes the move. The server log says what moved: Runtimes: <runtime> now runs on <path>, because the Node.js it was installed with is gone. A launcher still names its Node.js by full path, so nothing is looked up when it runs. A Node.js that is still there but that another user can change is never replaced this way, and on any other Node.js the runtime stays refused as above until you install it again.
When Clawboo will not use it
Clawboo installs nothing into the runtimes folder, and runs nothing from it, when:- it is the data folder or the work folder, sits inside one of them, or contains one of them. Clawboo compares real paths, so a link does not get around the check;
- its
bin/is a link, or not a folder; - the folder, its
bin/or a launcher belongs to another user, or others can write to it; - a folder above it lets anyone rename what is in it (others can write to it and it has no sticky bit), or holds a
node_modulesthat another user owns or can change. Node.js looks for a module an install lacks in thenode_modulesof every folder above it, so such a folder could stand in for part of a runtime.
PATH, if there is one, and an install fails with the reason. The server still starts. On Windows, ownership and write access are not checked.
must be apart from the work folder (<path>). Without CLAWBOO_RUNTIMES_DIR set, it starts with Clawboo's runtimes folder (<path>) instead. For a folder you do not own:
bin/ that is a link reads <path> is a link. Clawboo runs launchers only from a real folder: remove it and install again., and one that is not a folder reads <path> is not a folder. Move it away and install again. In an install’s event stream, each of these is the error code RUNTIMES_DIR_REFUSED.
Move or remove it
Nothing moves when you changeCLAWBOO_RUNTIMES_DIR. Stop Clawboo, set the variable, start Clawboo again, and install the runtimes again from Settings > Runtimes.
A reset of the data folder leaves the runtimes folder alone, and so does uninstalling Clawboo. To remove every runtime Clawboo installed, stop the OpenClaw Gateway if Clawboo started one (Manage, then Disconnect, on the OpenClaw row), stop the server, and delete the folder:
What Clawboo writes in OpenClaw’s folder
OpenClaw keeps its state in~/.openclaw (OPENCLAW_STATE_DIR moves it). Clawboo writes there in these cases:
On macOS and Linux, Clawboo makes
.env and each auth-profiles.json readable only by you (mode 0600) whenever it writes them, and creates ~/.openclaw owner-only (0700) if it does not exist yet. An existing ~/.openclaw keeps its mode.
Clawboo also reads openclaw.json (the Gateway’s port and token when settings.json has none), .env (the last place it looks for a provider key, after your environment and the vault), the agents’ auth-profiles.json (which providers OpenClaw has keys or sign-ins for), and state/openclaw.sqlite. It opens that database read-only, to show the standing command permissions on an OpenClaw agent’s Permissions tab and which browser tab belongs to which agent.
Keys you enter during onboarding or on a Runtimes card go only into the vault. See Providers and runtimes for where each kind of key is stored.
What a reset leaves behind
Resetting~/.clawboo never touches ~/.openclaw, so after a full reset:
- Keys you connected under Providers keep working. They are still in
~/.openclaw/.envand in the OpenClaw agents’auth-profiles.json, and Clawboo reads.envwhen its vault has no key. To remove them, disconnect each one under Settings > Providers before you reset, or delete their lines from those files. - Runtimes you disconnected can connect again on their own. Clawboo records a disconnect in
~/.clawboo, so after the reset a matching key in your shell or in~/.openclaw/.envreaches them again. - OpenClaw agents stay in OpenClaw, including agents Clawboo created, with their files. Clawboo finds the Gateway again from
openclaw.json. - The Gateway keeps Clawboo’s MCP entries. Clawboo rewrites them with a new attach token the next time it connects.
Back up your data
Back up the database
clawboo backup copies the database into one consistent file. It is safe to run while the server is running.
clawboo-backup-<date>-<time>.db in the current folder. Give it a folder to write the timestamped file there, or a file name. It refuses to replace an existing file unless you add -f (--force).
It copies the database only. The file holds all your teams, tasks, chats and memory, and the secret that signs MCP attach URLs, so on macOS and Linux it is readable only by you (mode 0600) from the moment it is created. If the backup fails, the partial file is removed. A backup made with 0.5.0 or older has your default file permissions; restrict it:
What else to copy
The database is most of your data, but not all of it. Copy these too when you need them:Back up everything
Stop the server and copy the whole folder. If you setCLAWBOO_HOME, use that folder in place of ~/.clawboo here and in the commands below:
With your own
STUDIO_ACCESS_TOKEN on the server, run clawboo stop and clawboo restart from a shell that has that token, so they can identify the server through the access gate. A server on its per-install token needs nothing: they read access-token. Without it, they print its port and a command that stops it by port, then exit without stopping it. Run that command, or stop Clawboo through the service manager that runs it (systemd, Docker), and start it again directly or through that service manager. clawboo backup works either way because it reads the database file directly. See the CLI reference.Restore
1
Stop the server
Run
clawboo stop, or stop the service that runs Clawboo.2
Put the backup in place
Copy the backup file over
~/.clawboo/clawboo.db, or replace ~/.clawboo with a whole-folder copy.3
Remove stale working files
If you restored a single-file backup, delete any
clawboo.db-wal and clawboo.db-shm left beside it from the old database.4
Start Clawboo
Run
clawboo. You should see your teams and board as they were when you made the backup.Hard reset
Reset only to wipe data. An upgrade needs no reset; see After an upgrade.Reset only the data
Reset everything
~/.openclaw (see What a reset leaves behind), the runtimes folder or the work folder. A new install’s cleanup never removes the old team folders and worktrees there, because its board does not record them. To remove them too, delete the work folder (rm -rf ~/clawboo-work, with the server stopped), which loses any uncommitted work in those worktrees, then run git worktree prune in each repository. Do that only when no other install uses the same work folder (through CLAWBOO_WORK_DIR): deleting it would remove that install’s team folders and checkouts too. A shared folder is cleaned by hand, removing only the reset install’s team folders and the checkouts whose .<task id>.owner file holds its id.
Two database paths
The server always usesclawboo.db in Clawboo’s folder (~/.clawboo/clawboo.db, or the same file under CLAWBOO_HOME). The four MCP stdio bins (clawboo-mcp-tasks, clawboo-mcp-memory, clawboo-mcp-tools, clawboo-mcp-teamchat) open the file named by CLAWBOO_DB_PATH instead, which defaults to ~/.openclaw/clawboo/clawboo.db and is created empty when missing. The two defaults differ on purpose.
For a stdio bin to see the server’s board and memory, set CLAWBOO_DB_PATH to the server’s database, or copy the stdio snippet from GET /api/mcp/config?transport=stdio, which sets it for you. The server itself ignores CLAWBOO_DB_PATH. See MCP servers.
The server log
A server started byclawboo writes its output to ~/.clawboo/server.log. When clawboo starts a server and the log is over 5 MB, it first moves the old log to server.log.1. If the dashboard has not answered after about 45 seconds, clawboo prints the last lines of this log and its path.
A server you start yourself, from a service manager or with node, writes to its own output instead. After the in-app update restarts the server, the new server’s output is not written to server.log; run clawboo restart to capture it again. An OpenClaw Gateway that Clawboo started logs to ~/.clawboo/gateway.log. The CLI reference covers starting, stopping and finding the server.
How Clawboo checks its data at startup
Each time it starts, Clawboo checks its folder, database and vault, and shows the results in Settings > System Health (and atGET /api/health).
The server keeps running either way, so you can read each check’s details in System Health: they say what is wrong and what to do. Treat a fatal check as broken until fixed, and use a full reset only as the last resort. When Master key fails, re-enter your provider keys and reconnect your connectors, or reset.
After an upgrade
When a new version first starts, it adds any columns the database is missing, so your data carries over with no step from you. It also turns on read-only Tasks and TeamChat for any Clawboo Native agent that has both turned off. That repair runs once and records that it ran, so turning either tool off afterwards sticks.Under the hood
Under the hood
- The database holds 51 tables and runs in SQLite’s WAL mode, which is why the
-waland-shmfiles sit beside it.clawboo backupuses SQLite’s online backup, so its copy needs no working files. See the database schema. clawboo stopsends the server a stop signal. On macOS and Linux the server stops its agent processes, folds the working files intoclawboo.dband closes it, so after a clean stopclawboo.dbalone holds every saved change. On Windows the process is ended at once with none of those steps, so copy the-waland-shmfiles with the database.- The
POST /api/system/configure-openclawroute, which no dashboard screen calls, replacesopenclaw.jsonand.envoutright and mints a new Gateway token. The dashboard’s OpenClaw setup uses the route that fills in only what is missing.
Related
- CLI reference:
clawboo backup,clawboo stop,clawboo restart, and howclawboofinds the server. - Environment variables:
CLAWBOO_HOME,CLAWBOO_WORK_DIR,CLAWBOO_RUNTIMES_DIR,CLAWBOO_DB_PATH,CLAWBOO_SECRETS_MASTER_KEY,OPENCLAW_STATE_DIR. - Security: the vault, the master key, and who can reach the server.
- MCP servers: attach outside agents and point the stdio bins at the right database.
- Database schema: every table in
clawboo.db.