<!-- Source: https://console.uubright.com/docs/backup/ -->
# 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](https://console.uubright.com/docs/tasks/) 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/alternates` is 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 `~/.claude` or
  `~/.codex` is 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](https://age-encryption.org) 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:

```sh
uubright backup create --out ~/work.scimigo-backup
```

On 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 ID` backs up one workspace (`uubright workspace list` shows the IDs).
  Without it, every workspace is included.
- The passphrase comes from `--passphrase-file FILE`, then the
  `SCIMIGO_BACKUP_PASSPHRASE` environment 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 DIR` reads another data folder (default `CCR_CLOUD_DATA`, or
  `~/.local/share/ccr-cloud`).

It prints how many tasks it saved, the size before and after compression, and the time:

```text
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:

```sh
uubright backup inspect ~/work.scimigo-backup
```

## Restore on another host

1. Sign in on the new host first: `claude auth login` (or `codex login`), and
   `gh auth login` if your projects are private. A restore clones each project again
   from its URL.
2. Copy the file over, for example `scp work.scimigo-backup my-host:`.
3. Stop the service. On a host the Mac app installed, or one set up with
   `npm run setup -- --start`, run `tmux kill-session -t ccr-cloud`; on a
   [systemd install](https://console.uubright.com/docs/aws-host/), `sudo systemctl stop ccr-cloud`.
   The restore refuses while the service is running, since the running service would
   overwrite what it writes.
4. Restore:

   ```sh
   uubright backup restore ~/work.scimigo-backup
   ```

   - `--src-root DIR` is where projects are cloned (default `~/src`): each goes to
     `DIR/<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-clone` skips cloning; clone the projects yourself before resuming.
   - `--data-dir DIR` restores into another data folder.
5. Start the service again: the Mac app's **Reconnect** starts it over SSH, or run
   `npm run setup -- --start` (`sudo systemctl start ccr-cloud` on 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~1` in 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`.
