Back up and restore
This guide covers the five things people actually do with backups: take one, collect it, move a workspace, put one back, and keep copies off the machine. For the exact shape of every artefact and operation, see the backup reference.
Everything here lives at Settings → Server → Backup & restore.
Prerequisites
Section titled “Prerequisites”- A full client — the desktop or web app. A paired phone can trigger none of this, by design.
- To take, list, download or delete an install snapshot: the install’s owner.
- For per-workspace actions: admin of that workspace to export it or to list and download its scheduled backups, owner to delete it or to delete one of its backups.
- To restore a workspace, from an uploaded file, a scheduled backup or a snapshot: the server owner, who must also be that workspace’s owner. A restore makes the server adopt a database file as its own, so it is the server owner’s call. Everyone else sees “Only the server owner can restore backups. You can still download them.” in place of the restore actions.
- For downloads and uploads: a paired full client on either a direct or brokered-relay connection. Both paths carry the file bytes through the same authenticated, end-to-end encrypted resource tunnel; the relay cannot read them.
What a backup covers
Section titled “What a backup covers”Both artefacts are databases only:
- An install snapshot is a timestamped directory:
manifest.json,global.dband one<workspaceId>/workspace.dbper workspace. - A workspace export is that single
workspace.dbfile.
A workspace’s database is the whole workspace: its conversations, run logs,
repository links, environment definitions and members. It holds no secrets:
pipeline webhook tokens, ticket-sync webhook secrets, provider sign-ins, device
keys and user secrets live in the global database and the server’s secret store.
It is still everything the workspace has said and done, so keep a downloaded
backup or export as private as the workspace itself. The code index is a separate
file beside the database, code_index.db. No backup carries it; the server
rebuilds it.
Neither carries the rest of the data directory: secrets.json (pairing keys, provider
credentials, webhook secrets, SSO), a workspace’s blobs/ (images pasted into messages), skills/,
agents/, chat_credentials/, recorded meeting audio or rig images. Some of that is
disposable and some of it is not — the
full table is in the reference,
and covering it is what the off-machine section is for.
Take a snapshot of the whole install
Section titled “Take a snapshot of the whole install”- Open Settings → Server → Backup & restore.
- Under Install snapshots, press Back up now.
- The toast names the directory that was written, on the server host. The new snapshot appears at the top of the list.
The server keeps running throughout. Each file is written with VACUUM INTO, which is
consistent against a live database, so there is no maintenance window and no need to stop
agents.
Each row in the list shows the timestamp, the size on disk, how many workspaces were captured and whether the snapshot is Complete or Unverified. Every copy is checked after it is written, and the manifest records its size and checksum. Unverified means the server cannot vouch for the snapshot: its manifest is missing or unreadable, or a file it names is absent or has changed size. That is a backup interrupted by a crash or a full disk, or one taken before snapshots recorded checksums. Those are still listed on purpose: a snapshot you cannot see is one you believe you have. An unverified snapshot cannot restore a whole install, but the workspace files it does hold can still be restored one at a time.
A row may also say n workspaces not captured. That is a workspace registered but never written to (there is no file yet), one whose database is damaged (a damaged copy is never taken), or one whose copy failed — check the server log.
A snapshot or scheduled backup marked Last good copy holds the newest good copy of a workspace whose database has since been damaged. Scheduled cleanup leaves it alone, and deleting it asks you to confirm, until that workspace is restored.
Schedule workspace backups and retention
Section titled “Schedule workspace backups and retention”Open Settings → Workspace → Pipeline templates for the workspace and find Workspace backup. Its enabled schedule runs every Sunday at 03:00 UTC: Back up workspace, followed by Delete backups older than (30 days by default). The second node runs only after the backup succeeds. You can change the retention days on the node or disable the schedule. If the server is offline at the scheduled time, the schedule catches up once when it comes back, rather than replaying every missed week.
Workspace backups live on the server under
backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. The retention
node deletes only old backups for this workspace; it never deletes install snapshots
or backups for other workspaces. These files are database-only. For off-machine
retention, download them or copy them independently.
Find and restore a scheduled backup
Section titled “Find and restore a scheduled backup”Scheduled backups sits between Install snapshots and Workspace data, with one row per workspace: when its last backup ran, how many it has kept and the space they take. A workspace whose pipeline has not produced anything says No backups yet. A workspace you are not an admin of says so in its row instead of listing its backups.
Expand a row to see each backup, newest first:
- Restore replaces the workspace’s current database with this backup. The database it replaces is kept in this list, under a name ending in
-pre-restore, so you can go back. Needs the server owner, who must also own the workspace. - Download saves the file on the machine you are using. The backup stays on the server.
- Copy path copies its location on the server.
- Delete removes this backup permanently, once you type the workspace’s name. Needs owner.
Backups of a deleted workspace
Section titled “Backups of a deleted workspace”Deleting a workspace leaves its scheduled backups on the server, and because its schedule stops with it, retention stops too: they stay until someone removes them. The install owner sees them in the same list, marked Workspace deleted, and can download or delete them there. Nobody else sees those rows.
They have no Restore, since there is no workspace to restore into. To bring one back, download it, create a workspace (only the server owner can), and upload the file as described in Move a workspace to another install.
Delete an install snapshot
Section titled “Delete an install snapshot”Under Install snapshots, expand the snapshot, including an unverified one, and use Delete snapshot in the danger section. Confirm its name. The entire snapshot directory is permanently removed from the server; download it first if you need a copy. A workspace backup pipeline never deletes these snapshots.
Collect a copy on your own machine
Section titled “Collect a copy on your own machine”The paths the page shows are on the machine running cc_server. When that is not the
machine you are sitting at, use the Download buttons:
- Beside each workspace under Workspace data → Download, for one
.dbfile. - Beside each snapshot under Install snapshots → Download, for the whole snapshot as a
.zip. - Beside each backup under Scheduled backups → Download, for that backup’s
.dbfile.
On desktop you pick where the file lands and the toast names it; on web it goes to the browser’s downloads. Either way all three report progress in bytes, because these payloads run to gigabytes.
The workspace and snapshot downloads mint a fresh copy at the moment you press the button, stream it, and delete the server’s copy afterwards — a download is not “fetch the file the export button made earlier”. A scheduled backup is the exception: you get the stored file, and it stays on the server.
Unzipping a snapshot archive reproduces the snapshot layout exactly, which is what makes restoring it a copy back.
Move a workspace to another install
Section titled “Move a workspace to another install”One workspace is one database file, so handing it over is a file operation.
- On the source server, Settings → Server → Backup & restore → Workspace data, expand the workspace and press Download.
- On the destination server, create (or pick) the workspace that will receive it.
- Expand that workspace, and under Restore from this device press Choose a file and upload. Pick the
.dbyou downloaded.
Step 3 is a restore, so it needs the destination’s server owner, who must also own that workspace.
If both servers are the same machine you are sitting at, Save on server on the source, then the file’s path in Workspace database file and Import on the destination, does the same thing without the round trip; that path resolves on the server host.
A file from another workspace or from a different install is accepted: that is how you duplicate a workspace, restore it under a new id or hand it to somebody else. User ids from another install do not resolve on this one — the workspace’s own data is intact, but re-check membership after adopting it.
A restored file cannot grant anything on this server by itself. The permissions it carried beyond ordinary membership are taken out and listed under Held back from restored copies at the top of the page: action rules that let agents act without approval or after one, paths a sandbox may run, repository access above read, roles above member and open invites to those roles. Accept grants one again; Dismiss drops it. Approvals to run an environment definition on the host are cleared, so approve those definitions again. Whoever restores keeps or gets the owner role.
Chat bot tokens, provider sign-ins and webhook secrets live outside the database, so the receiving install connects its own. Webhook triggers and ticket-sync webhooks arrive without their secrets and receive nothing on another server until you save them again there, which gives each trigger a new URL.
Restore one workspace from a snapshot
Section titled “Restore one workspace from a snapshot”You need to be the server owner and the workspace’s owner.
- Under Install snapshots, expand the snapshot you want.
- Find the workspace’s row and press Restore.
- Confirm. Everything that workspace has done since the snapshot was taken is lost.
This is the same operation as an import, pointed at the snapshot’s copy of that workspace’s file — deliberately, so there is no second mechanism that could treat the same file differently. The copy is first checked against the checksum the snapshot recorded.
A row may say Not on this server any more, with Restore disabled: the snapshot
holds a workspace this install no longer has. Bring it back by hand — create a workspace (server owner only),
then under Workspace data enter
<snapshot path>/<old workspace id>/workspace.db in its Workspace database file
field and press Import. The expanded snapshot shows its own
Path on the server in a copy field, and the row’s title is the old workspace id, so
you have both halves of that path in front of you.
Restore a damaged workspace
Section titled “Restore a damaged workspace”A workspace whose database fails its integrity check turns read-only: everything stays
readable and every change is refused. Members see This workspace is read-only at the
top of the workspace, the server owner sees it under Needs your attention on this
page, and the newest backup that holds a good copy is kept as Last good copy.
Restore the workspace from that copy, as described above, to make it writable again.
The damaged database is kept as a -pre-restore backup.
Restore a whole install
Section titled “Restore a whole install”There is no button for this, and there should not be: it replaces the databases the running server is holding open.
-
Stop
cc_server. If you run the desktop app with its embedded server, quit the app. -
Copy the snapshot’s contents over the data directory. The snapshot layout mirrors the live one, so this is a plain copy:
Terminal window # macOS default; see the CLI reference for other platformsDATA_DIR="$HOME/Library/Application Support/control-center"SNAPSHOT="$DATA_DIR/backups/2026-07-28T09-12-33-000Z"cp "$SNAPSHOT/global.db" "$DATA_DIR/global.db"for d in "$SNAPSHOT"/*/; doid=$(basename "$d")mkdir -p "$DATA_DIR/$id"cp "$d/workspace.db" "$DATA_DIR/$id/workspace.db"done -
Delete any
-waland-shmfiles sitting next to the databases you replaced. They belong to the old files and a stale one alongside a restored database is a corruption risk. -
Start the server again.
The snapshot holds no secrets.json, so an install restored onto a fresh host keeps
its data but not its credentials: paired devices, provider tokens and SSO settings have to
be re-established, or restored from wherever you kept that file. Restoring onto the same
host, where secrets.json was never lost, keeps everything.
Copy backups off the machine
Section titled “Copy backups off the machine”A snapshot on the same disk as the database it copied protects you from a bad import, not from the disk. Nothing in Control Center ships a copy anywhere, so this part is yours.
Sync the snapshots
Section titled “Sync the snapshots”Snapshots are immutable once written and named by timestamp, so any sync tool handles
them well. Exclude transfer/, which is a workbench for in-flight downloads and uploads:
DATA_DIR="$HOME/Library/Application Support/control-center"
# To another host over sshrsync -a --delete --exclude 'transfer/' \ "$DATA_DIR/backups/" backup-host:/srv/control-center-backups/
# To object storageaws s3 sync --exclude 'transfer/*' \ "$DATA_DIR/backups/" s3://my-bucket/control-center/backups/
# Or with deduplication, encryption and its own retentionrestic backup --exclude 'transfer' "$DATA_DIR/backups"--delete mirrors your local pruning to the remote. Drop it if you want the remote to
keep snapshots longer than the host does.
Include what a snapshot leaves out
Section titled “Include what a snapshot leaves out”To be able to rebuild the install rather than just its data, copy these too. They are ordinary files, safe to copy while the server runs:
rsync -a \ "$DATA_DIR/secrets.json" \ backup-host:/srv/control-center-backups/config/
rsync -a --relative \ "$DATA_DIR"/./*/chat_credentials \ "$DATA_DIR"/./*/blobs \ "$DATA_DIR"/./*/skills \ "$DATA_DIR"/./*/agents \ backup-host:/srv/control-center-backups/workspace-files/secrets.json is 0600 and holds every pairing key, provider credential and SSO setting
on the install. Wherever it lands must be at least as protected as the server host —
encrypted at rest, and not a bucket anyone else can read.
Skip spaces/ (copy-on-write worktrees, re-provisioned from your repos), pr_clones/
(a cache), models/ (re-downloaded), media_cache/ and rigs/ (machine state, and
large). Recorded meeting audio under meetings/ is worth including if you keep meetings.
Schedule a whole-install snapshot outside the app
Section titled “Schedule a whole-install snapshot outside the app”The built-in pipeline backs up only one workspace. For an unattended whole-install
snapshot, there is no CLI subcommand, and the snapshot RPC requires a paired full
client that is the install owner. A host-side timer can use VACUUM INTO against
the live databases:
#!/usr/bin/env bashset -euo pipefail
DATA_DIR="${CC_SERVER_DATA_DIR:-$HOME/.local/share/control-center}"DEST="/srv/control-center-snapshots/$(date -u +%Y-%m-%dT%H-%M-%SZ)"mkdir -p "$DEST"
sqlite3 "$DATA_DIR/global.db" "VACUUM INTO '$DEST/global.db'"
for db in "$DATA_DIR"/*/workspace.db; do id=$(basename "$(dirname "$db")") mkdir -p "$DEST/$id" sqlite3 "$db" "VACUUM INTO '$DEST/$id/workspace.db'"doneRun it as the same user that owns the data directory, from cron or a systemd timer, and
sync DEST off the host afterwards. VACUUM INTO needs SQLite 3.27 or newer.
Write it outside <dataDir>/backups/. A hand-made directory there has no
manifest.json, so the app would list it as an unverified snapshot and the list would
stop being an honest record of what the server itself produced.
Prune old whole-install snapshots
Section titled “Prune old whole-install snapshots”You can delete individual install snapshots in the app. For a host-side retention policy, keep the workspace backup directory separate from the install snapshots:
find "$DATA_DIR/backups" -mindepth 1 -maxdepth 1 -type d \ ! -name exports ! -name transfer ! -name workspace-backups \ -mtime +30 -exec rm -rf {} +Check the output of a -print run before adding -exec. Keep more than one: the failure
you are protecting against is often “the last backup also has the problem”.
Check that a backup is good
Section titled “Check that a backup is good”A backup nobody has restored is a hypothesis.
Cheap check — the file opens and its pages are intact:
sqlite3 "$SNAPSHOT/global.db" 'PRAGMA integrity_check;' # expects: okReal check — adopt it. Create a scratch workspace on a non-production install, import a workspace file into it, and look at whether the spaces, tickets and messages you expect are there. That exercises the same path a real restore takes, including the FTS rebuild, and it is the only check that tells you the backup is restorable rather than merely readable.
Do this once when you set backups up, and again whenever you change where they are stored.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause and fix |
|---|---|
| Download or upload fails after a connection changes | Retry on the active paired connection. Direct and relay both support encrypted file transfer; neither exposes a plaintext HTTP fallback |
| “The server refused. Downloading a workspace needs the workspace admin role. Restoring one needs the server owner, who must also own the workspace. A whole snapshot needs the server owner.” | Role. Taking, listing or downloading an install snapshot needs the server owner. Downloading a workspace needs admin; restoring one needs the server owner, who must also own the workspace |
| “File transfers aren’t set up for this connection yet. Reconnect to the server to download or upload a backup.” | This connection to the server has no file transfer lane, so Download and the upload are turned off. Reconnect to the server, then try again |
| “Only the server owner can restore backups. You can still download them.” | Restoring replaces a workspace’s database on the server host, so only the server owner restores. Download the backup and ask them |
| “This server has no backup surface.” | The host has no backup port wired — a demo server. The operations are absent rather than refused |
| “The file is larger than the server accepts.” | Uploads are capped at 8 GiB. Put the file on the server host and enter its path in Workspace database file |
| A restore is refused and nothing is replaced | The file failed a check, and the message says which: it is not a workspace database, it is damaged, it differs from the checksum its snapshot recorded, a newer version of the server wrote it, or its webhooks or invites already belong to another workspace on this server. Use another copy, or update the server first |
| A snapshot is listed Unverified | It never finished, or it was taken before snapshots recorded checksums. Take a fresh one; restore individual workspace files from it in the meantime |
| A snapshot says workspaces were not captured | Those workspaces have never been written to, are damaged, or their copy failed. Check the server log |
| A workspace says This workspace is read-only | Its database failed an integrity check. Nothing in it can be changed until the server owner restores it from a backup |
| Webhooks stop arriving after a workspace moves to another server | Webhook secrets do not travel with the database. Save each webhook trigger and ticket-sync connection again on the new server, then give the sender the new URL |
| A restored install has no forge or SSO credentials | secrets.json is not in a snapshot. Restore it from wherever you kept it, or reconnect the providers |
| A restored workspace is missing pasted images | Blobs live beside the database, not in it. Copy <workspaceId>/blobs/ across as well |
Related guides
Section titled “Related guides”- Run a headless server: where the data directory comes from
- Connect to a remote server: direct versus relayed connections
- Pair a device: the paired device credential used by the encrypted transfer and its signed resource requests
Related concepts and reference
Section titled “Related concepts and reference”- Backup, export and import: every operation, route, field and limit
- Workspaces and isolation: why one workspace is one file
cc_serverCLI: the data directory layout