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.
Artefacts
Section titled “Artefacts”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.
Snapshot layout
Section titled “Snapshot layout”<dataDir>/backups/2026-07-28T09-12-33-000Z/ manifest.json global.db <workspaceId>/workspace.db one directory per workspaceThe 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.
manifest.json
Section titled “manifest.json”| 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.
Completeness
Section titled “Completeness”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.
What a backup does not contain
Section titled “What a backup does not contain”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.
Operations
Section titled “Operations”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.deleteis unscoped because the row it marks lives in the global registry; its handler checks the caller’s membership of the named workspace and requiresowner.
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.
server.listBackups response
Section titled “server.listBackups response”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.
workspace.import validation
Section titled “workspace.import validation”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.
Transfer routes
Section titled “Transfer routes”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.
Paths and limits
Section titled “Paths and limits”| 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.
See also
Section titled “See also”- Back up and restore — the recipes these operations belong to
- Workspaces and isolation — why one workspace is one file
cc_serverCLI — the data directory these paths sit in- Route map — where the UI lives
- Architecture — the client/server split the paths follow