Back up and restore a workspace
A backup is one encrypted file. It holds a workspace and its tasks, so you can move your work to another host, such as a new cloud host, and carry on there. Restored tasks come back stopped. Resume continues each one with its conversation, its branch and its uncommitted work.
This is a beta feature. Backups are made and restored on the server's command line.
#What a backup holds
- Workspaces: name, mode, instructions, Git author name and email, the Manager assignment and defaults. The list of add-ons is noted, but not the add-ons themselves or their secrets.
- Projects: repository URLs and base branches, not the clones. A restore clones them again.
- Tasks: records, event logs (the conversations), drafts, uploads, deliverables, chat projects and their memory notes, and the rooms in the workspace.
- Code: each task's branch and its uncommitted work, as a git bundle. Changed and untracked files are saved as a WIP commit on top of the branch, with the same checks Retire uses. The checkout itself isn't touched: nothing is staged, committed or moved there. A live checkout's bundle carries the commits origin lacks; a retired task's thin bundle is expanded with any prerequisite commits so it works on a clean host. A scratch task's regular files are copied without installed dependencies. Executable bits and links within the scratch workspace are kept; links outside it and special files are reported as omissions. Scratch Git history (
.git) is scanned as Git objects, including unreachable objects, before it is copied. Nested scratch repositories and stored submodule object stores are scanned separately. If a credential pattern matches, that repository's history is omitted with a warning. Empty Git metadata directories are kept. A scratch repository borrowing objects through.git/objects/info/alternatesis repacked into a private copy and checked without the original object store; if that fails, its history is omitted with a warning. Git hooks and LFS metadata are omitted. Export those separately if they matter. - The agent's session: the task's own Claude Code session files, or its Codex thread, so Resume continues the same conversation. Nothing else from
~/.claudeor~/.codexis included.
#What a backup leaves out
- Credential files. Claude Code, Codex and GitHub logins; the owner token and device tokens; relay keys and the registration secret; push and APNs tokens; add-on secrets; task runner tokens;
server.env. The backup copies a fixed list of records, not the data folder, so these files are never read into it. - Credentials inside conversations. An agent may have printed a token into its conversation. Before anything is written, the backup collects every credential this host keeps, from the files above and from each task's environment. Each one found in a conversation, session file, record or upload is replaced with
[redacted]. So are well-known token shapes (GitHub, Anthropic, OpenAI, AWS, Slack, Google, private keys). Chat project uploads are treated as content, not as a source of credential values; ordinary identifiers in them are retained unless they match a known credential. - Ignored files in a task's checkout, such as
.env, and files named like credentials in a scratch task. Make them again on the new host. - Code holding a credential. A git commit can't be redacted. Every file and commit message going into a task's bundle is read as it is stored, without diff settings that could hide it. If one contains a credential the host keeps or a well-known token shape, the task's code is left out and the backup says so; the rest of the task is still backed up.
- A binary upload that contains a known credential or matching token shape is left out, with a note. Media files over 64 MB are copied without a content scan.
- PR review tasks: ask for a new review on the new host.
The backup command prints notes for exclusions it detects. It cannot identify every secret in arbitrary conversations, uploads or code, so keep the encrypted archive private and inspect the notes before relying on it as the only copy of your work.
#Encryption
The file is encrypted on the host before it is written, with a passphrase you hold. It uses the age format with a scrypt passphrase: scrypt makes each passphrase guess slow and memory-hungry. The contents are authenticated in 64 KiB chunks, so a changed or truncated file is refused rather than restored. Because age is a published format, the standard age tool can also open a backup (age -d): it holds a zstd-compressed tar archive.
Keep the passphrase apart from the file. Without it the backup can't be restored, and uuBright Console can't recover it for you.
#Make a backup
On the host, with the service running or stopped:
uubright backup create --out ~/work.scimigo-backupOn a host installed by the Mac app, run it as node ~/.uubright/current/src/cli/bin.ts backup create --out ~/work.scimigo-backup. With a standalone server package, use npm run backup -- create --out ~/work.scimigo-backup.
--workspace IDbacks up one workspace (uubright workspace listshows the IDs). Without it, every workspace is included.- The passphrase comes from
--passphrase-file FILE, then theSCIMIGO_BACKUP_PASSPHRASEenvironment variable, then a prompt. Press Enter at the prompt and it makes a strong passphrase and prints it once. Without a terminal it needs one of the first two. - It refuses to replace an existing file.
--data-dir DIRreads another data folder (defaultCCR_CLOUD_DATA, or~/.local/share/ccr-cloud).
It prints how many tasks it saved, the size before and after compression, and the time:
Backed up 12 tasks (3 with uncommitted work) from 1 workspace: 66.3 MB → 2.1 MB in 4.2 s.
Encrypted with your passphrase (age, scrypt). 2 credential matches found in conversations and files were replaced with [redacted].
Tasks that are running are saved as they are at that moment, like after a power cut, and the backup says so. For a clean copy, back up when tasks are idle or stopped.
To see what a backup holds without restoring it:
uubright backup inspect ~/work.scimigo-backup#Restore on another host
- Sign in on the new host first:
claude auth login(orcodex login), andgh auth loginif your projects are private. A restore clones each project again from its URL. - Copy the file over, for example
scp work.scimigo-backup my-host:. - Stop the service. On a host the Mac app installed, or one set up with
npm run setup -- --start, runtmux kill-session -t ccr-cloud; on a systemd install,sudo systemctl stop ccr-cloud. The restore refuses while the service is running, since the running service would overwrite what it writes. Restore:
SHELLuubright backup restore ~/work.scimigo-backup--src-root DIRis where projects are cloned (default~/src): each goes toDIR/<its folder name>. If two projects share a folder name, the second gets its project ID appended. An existing repository is used only when its origin matches the project record.--no-cloneskips cloning; clone the projects yourself before resuming.--data-dir DIRrestores into another data folder.
- Start the service again: the Mac app's Reconnect starts it over SSH, or run
npm run setup -- --start(sudo systemctl start ccr-cloudon a systemd install). Open a restored task and choose Resume.
On Resume, the task's checkout is made again from the clone, with its branch and the WIP commit from the backup on top. Its agent continues the same conversation.
Restoring refuses an existing task that is not part of an interrupted restore. An interrupted restore leaves a .restoring marker in each task folder until all tasks, drafts, deliverables and rooms are done; rerunning the same archive restarts those marked tasks and finishes the remaining steps. Existing agent session files are kept. The exception is a workspace that already exists: its name, instructions, Git author, Manager and defaults are taken from the backup, and it keeps its own logins and add-ons.
#After restoring
- Your uncommitted work is a WIP commit at the top of the task's branch, as after Retire. To have it as uncommitted changes again, run
git reset HEAD~1in the checkout. - Install and enable add-ons again; the restore lists the ones the workspace used.
- Set a workspace's own GitHub token or logins again if it had them.
- Project setup variables named like credentials were left out; set them again.
#Speed
Everything streams: tar, then zstd compression, then encryption, straight to the file. Tasks' code snapshots run several at a time. On a heavily loaded 8-core server, a workspace of 20 tasks, each a worktree of a 3,000-file repository with uncommitted changes, a 2 MB conversation and a 1 MB Claude session, backed up in about 15 s and restored, with a fresh clone, in about 9 s. To measure your own: node scripts/backup-bench.ts 20.