Skip to content

Backup, export and import

Everything Control Center can copy, hand over or adopt, and the exact shape of each artefact. To actually take a backup, see Back up and restore; for why persistence is split this way, see Workspaces and isolation.

There are three database-copy artefacts, with different scopes and deletion policies.

Artefact Written by Shape Covers
Install snapshot server.backupNow A timestamped directory Every database on the install
Workspace backup Workspace backup pipeline Timestamped directory with one .db One workspace’s database
Workspace export workspace.export A single .db file One workspace’s database

All are written with SQLite VACUUM INTO, which is safe against a live WAL database: it takes a read transaction, produces a defragmented and transactionally consistent copy, and never requires stopping the server.

These files and downloaded copies are not encrypted at rest by Control Center. The end-to-end encrypted transfer protects bytes in transit between a paired client and its cc_server, on either direct or brokered-relay connections. Protect local storage and off-machine copies separately; the server and any authorised recipient can read the database files.

<dataDir>/backups/2026-07-28T09-12-33-000Z/
manifest.json
global.db
<workspaceId>/workspace.db one directory per workspace

The layout mirrors the live data directory exactly, which is what makes restoring an install a copy back rather than a translation. The directory name is the UTC timestamp with : and . replaced by -, so it is filesystem-safe on Windows and sorts chronologically as a plain string.

Scheduled workspace backups live separately at <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db. Each has a manifest.json for that one file and no global.db; they are not install snapshots. A restore keeps the database it replaces in the same place, as <timestamp>-pre-restore. The weekly pipeline’s retention step removes only backups of its own workspace older than its configured age (30 days by default); manually created install snapshots are never rotated by that step. server.listBackups lists only install snapshots, including unverified ones; workspace.listBackups lists one workspace’s scheduled backups.

Deleting a workspace leaves this directory in place. The workspace’s schedule stops with it, so nothing rotates those backups any more, and they stay until the install owner removes them. server.listOrphanedBackups reports them.

Field Type Meaning
format int Manifest format. Currently 2
created_at ISO-8601 UTC When the snapshot was taken
global object The record of global.db. Absent from a scheduled workspace backup
workspaces[] array One record per captured workspace
workspaces[].workspace_id string The workspace this file holds
skipped_workspaces[] array Workspaces the backup could not capture
skipped_workspaces[].workspace_id string The workspace that was left out
skipped_workspaces[].reason string no_file, damaged or failed

global and each entry of workspaces[] record one copied file, measured on the copy after it was written:

Field Type Meaning
file string Path relative to the snapshot root: global.db or <workspaceId>/workspace.db
bytes int Size of the copy
sha256 string SHA-256 of the copy, in lowercase hex
quick_check string What SQLite’s quick_check said about the copy: ok, or its finding
user_version int Schema version of the copy
application_id int SQLite application_id of the copy

A workspace is skipped when it is registered but has never been written to (no_file), when its database fails the integrity check (damaged; a damaged copy is never taken), or when its copy or the check of that copy failed (failed). Either way the snapshot still completes and the manifest names what is missing. The manifest is written last.

server.listBackups reports a complete flag per snapshot. It is false when the manifest is absent, unparseable or of another format, when a file it names is missing or has another size, or when a copy did not pass its check. The app shows such a snapshot as Unverified. Snapshots taken before format 2 are in that state.

An unverified snapshot is still listed, because a snapshot an operator cannot see is a snapshot they believe they have. When the manifest is unreadable the listing falls back to the layout itself and reports whichever <workspaceId>/workspace.db files it finds — those remain individually adoptable through workspace.import even though the snapshot as a whole cannot restore an install.

A listed snapshot or scheduled backup carries pinned_reason: "last_good_copy" while it holds the newest verified copy of a workspace whose live database is damaged. The retention step skips it until that workspace is restored.

Both artefacts are databases only. A workspace directory holds more than its database, and none of the rest travels:

Path In a snapshot? In a workspace export?
global.db Yes No
<workspaceId>/workspace.db Yes Yes (it is the file)
<workspaceId>/code_index.db No No
<workspaceId>/blobs/ No No
<workspaceId>/skills/ No No
<workspaceId>/agents/ No No
<workspaceId>/chat_credentials/ No No
<workspaceId>/spaces/<spaceId>/ No No
<workspaceId>/pr_clones/ No No
secrets.json No No
models/ No No
meetings/<meetingId>/ No No
rigs/ No No
_agent_hooks/ No No

Some of that is disposable — spaces/ holds copy-on-write worktrees that are re-provisioned from the repos, pr_clones/ is a cache, code_index.db is rebuilt, models/ re-downloads, rigs/ is machine state. Some of it is not: blobs/ holds pasted images that rows in the database point at, skills/ and agents/ hold the files an agent runs with, and secrets.json holds every pairing key, provider credential and SSO setting on the install. See Back up and restore for covering the rest.

Install backup RPCs and workspace export/import are fullClient-only: a paired phone cannot trigger them. All are absent entirely — not refused, structurally missing — on a server with no backup port wired, such as the demo server.

Op Kind Scope Minimum role Arguments Returns
server.backupNow mutate Install install owner none {ok, path}
server.listBackups read Install install owner none {backups: [...]}
server.deleteBackup mutate Install install owner name {ok}
server.listOrphanedBackups read Install install owner none {workspaces: [...]}
server.deleteOrphanedBackup mutate Install install owner workspace_id, name {ok}
workspace.listBackups read Workspace admin none {backups: [...]}
workspace.deleteBackup mutate Workspace owner name {ok}
workspace.export read Workspace admin none {ok, path}
workspace.import mutate Workspace owner, and the server owner source_path {ok, workspace_id}
workspace.importHolds.list read Workspace owner, and the server owner none {holds: [...]}
workspace.importHolds.resolve mutate Workspace owner, and the server owner hold_id, accept {ok, applied}
workspace.delete mutate Install* owner id registry row marked deleted
  • workspace.delete is unscoped because the row it marks lives in the global registry; its handler checks the caller’s membership of the named workspace and requires owner.

path in every response is a path on the server host.

server.listOrphanedBackups returns one entry per workspace that is no longer live: workspace_id, workspace_name when the registry still knows it, and backups. A deleted workspace can no longer pass a workspace role check, so its backups belong to the install owner. server.deleteOrphanedBackup refuses a live workspace, whose backups stay behind workspace.deleteBackup and that workspace’s own roles. Both delete ops accept only a listed timestamp directory name, not a path.

workspace.importHolds.list returns what an import held back. Each hold has an id, a kind (action_policy, sandbox_exec_grant, repo_grant, membership_role or invite), the payload it would put back, imported_at and source_install_id. workspace.importHolds.resolve with accept: true grants it again and with false drops it. applied is false when whoever or whatever the grant was for is no longer in the workspace.

Newest first, sorted by directory name (which is the timestamp, so the order holds even for a snapshot whose manifest could not be read).

{
"backups": [
{
"path": "/…/backups/2026-07-28T09-12-33-000Z",
"name": "2026-07-28T09-12-33-000Z",
"created_at": "2026-07-28T09:12:33.000Z",
"bytes": 481203712,
"complete": true,
"workspaces": [
{
"workspace_id": "w_9f2c…",
"path": "/…/backups/2026-07-28T09-12-33-000Z/w_9f2c…/workspace.db",
"bytes": 190840832
}
],
"skipped_workspace_ids": []
}
]
}

created_at is omitted when the manifest could not be read. bytes at the top level is the real size on disk of the whole directory, not the manifest’s own sum — the question an operator pruning snapshots is asking is what the directory costs, not what the backup meant to write.

Each workspaces[].path is exactly what workspace.import takes as source_path. That is deliberate: “restore this workspace from this snapshot” is the import op, so the two cannot drift into different treatments of the same file.

Before anything is replaced, the candidate file is copied to a staging file beside the target and checked there. A refusal touches nothing and carries its kind as data.kind.

Condition Result
The file does not exist Refused, import.missing_source
Not a readable SQLite database, or it fails quick_check Refused, import.damaged
It comes from a snapshot and its SHA-256 differs from the manifest’s Refused, import.checksum_mismatch
A newer version of the server wrote it Refused, import.newer_schema
Another application_id, or no workspace_meta Refused, import.foreign_file
It cannot be brought to this server’s schema Refused, import.schema_mismatch
Its webhooks or invites already route to another workspace Refused, import.route_conflict
Recorded workspace id ≠ the target Allowed. Its rows are re-keyed to the target. This is how a workspace is duplicated or restored under a new id
Recorded install id ≠ this install Allowed. Its user ids belong to that install and will not resolve here

On acceptance the staged file is brought to this server’s schema and must then match it exactly. Grants a file may not give itself are taken out of it: approvals to run an environment definition on the host are cleared, and action rules that allow or prompt, sandbox exec grants, repository grants above read, roles above member and invites to those roles become holds for the server owner to review. The importer keeps or gets the owner role. The database being replaced is kept as a scheduled backup named <timestamp>-pre-restore, the staged file is renamed into place with the workspace’s connections closed, code_index.db is deleted to be rebuilt, and the FTS indexes are rebuilt.

The export/import and snapshot listing operations above speak in server-side paths, which is a complete answer only when the server is your own machine. These HTTP-shaped routes carry backup bytes inside the same authenticated, end-to-end encrypted resource tunnel as other sensitive resources, whether the RPC connection is direct or brokered. They are not public HTTP file-transfer endpoints: a request to one on the public listener returns 426 Upgrade Required, even from loopback. In the encrypted tunnel, the Noise-authenticated device must match d; the handler additionally checks the device’s signature over its target string using its pairing PSK and the role below.

Route Method Query Signed target Requires
/backup/workspace GET w, d, s backup-workspace:<workspaceId> Workspace admin
/backup/snapshot GET n, d, s backup-snapshot:<name> Install owner
/backup/stored GET w, n, d, s backup-stored:<workspaceId>:<name> Workspace admin; install owner once the workspace is deleted
/backup/restore POST w, d, s backup-restore:<workspaceId> Install owner who is also workspace owner (403 with server_owner_required otherwise)

w is a workspace id, n a snapshot or scheduled backup directory name, d the calling device id, s the signature. On /backup/snapshot, n is resolved against the backup listing rather than joined onto the backups root, so the route cannot be aimed at a directory the listing would not have shown. On /backup/stored it must be a timestamp name, and the file must be a real file inside that workspace’s own backup directory.

Status Cause
400 A required query parameter is missing, a backup name is invalid, an upload body is empty, or the uploaded file was refused (the body is {error, kind} with an import.* kind)
403 Unknown or revoked device, bad signature, or the caller lacks the role
404 No backup port on this host, or the named snapshot, backup or workspace file does not exist
405 /backup/restore called with anything but POST
413 Upload body exceeds 8 GiB, by declared content-length or by bytes actually read
426 Any direct request to a transfer path on the public HTTP listener; use a paired client’s encrypted resource tunnel
500 The export or archive failed server-side

All three downloads respond Cache-Control: no-store with Accept-Ranges: none. /backup/workspace and /backup/snapshot mint a fresh copy per request and delete it once streamed, so a cached or resumed response would splice bytes from two different exports into one file that looks valid and is not.

/backup/stored is the exception: it streams a scheduled backup as <workspaceId>-<name>.db and leaves the file in place, because that file is the backup.

/backup/snapshot returns <name>.zip, entries relative to the snapshot root so unpacking reproduces manifest.json + global.db + <workspaceId>/workspace.db. Entries are written in sorted order, so two archives of the same snapshot are the same archive.

/backup/restore streams the body straight to a staging file rather than buffering it, bounds it before and during the read, and deletes the staged file on every path out including a refusal.

Thing Value
Snapshots <dataDir>/backups/<timestamp>/
Scheduled workspace backups <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>/workspace.db
Workspace exports <dataDir>/backups/exports/<workspaceId>-<timestamp>.db
Database replaced by a restore <dataDir>/backups/workspace-backups/<workspaceId>/<timestamp>-pre-restore/
Databases as they were before an update changed their format <dataDir>/pre_upgrade/ and <dataDir>/<workspaceId>/pre_upgrade/, the newest two of each
Transfer staging <dataDir>/backups/transfer/ — a workbench, swept by the route that writes it
Snapshot archive name <snapshot directory name>.zip
Upload ceiling 8 GiB per encrypted /backup/restore upload
Retention Install snapshots: manual deletion. Workspace backups: weekly pipeline, 30-day default, or manual deletion. Backups of a deleted workspace: manual deletion only

The exports/, transfer/, and workspace-backups/ directories are not install snapshots and are excluded from server.listBackups. Only the last directory has scheduled retention, and only while its workspace exists; deleting an install snapshot requires the install owner’s explicit action.