---
title: "Back up and restore"
description: "What lives in Cloudflare, what lives in your project folder, and what to keep."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-orbs-site.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Back up and restore

Running orbs need nothing on your machine. The project folder only holds your settings and the files the CLI uses to manage the install. Keep a copy of the small part you can't make again.

## What lives in Cloudflare

With `providerHost` set to `cloudflare` (the default), your Cloudflare account holds:

- The Worker, with its Durable Objects: the orbs, the registry and the provider host.
- The provider container and the orb containers.
- Orb disks and snapshots.
- The Amp provider token, as the Worker secret `AMP_ORB_PROVIDER_TOKEN`.
- The control token, as the Worker secret `CONTROL_TOKEN`.

If you lose your laptop, running and paused orbs stay as they are, and new Amp threads still start.

## What lives in the project folder

| File | What it is | If you lose it | How to get it back |
| --- | --- | --- | --- |
| `cf-orbs.config.jsonc` | Your settings (name, size, limits, images) | `init` writes the defaults. Your changes are gone | Restore from your backup. Or set the values again |
| `image/Dockerfile` | The orb image | `init` writes the default Dockerfile. Your toolchains are gone | Restore from your backup |
| `image/<key>.Dockerfile` | An older orb image that `upgrade` kept. Paused orbs use it | A paused orb that needs this key cannot start from it. The Worker reports `image key <key> is not deployed` | Restore from your backup |
| `.cf-orbs/control-token` | The key the CLI uses for the Worker `/v1` API | `init` makes a new token and sets it on the Worker. The old token stops working | Run `cf-orbs init`. Update every other place that used the old token |
| `.cf-orbs/state.json` | Worker URL, account, Worker name, provider name, CLI version. No tokens | `deploy` writes it again with the URL. The provider name is lost: pass `--provider-name` | Run `cf-orbs init --adopt` with the same Worker name and account. Pass `--provider-name` |
| `.cf-orbs/wrangler.jsonc`, `.cf-orbs/worker/`, `.cf-orbs/provider/`, `.cf-orbs/dispatch/` | Generated files | Nothing. `deploy` writes them again | Run `cf-orbs deploy` |

## What to back up

The minimum:

- `cf-orbs.config.jsonc`
- `image/` (the Dockerfile and any `image/<key>.Dockerfile`)
- The Amp provider token, if you want to restore without making a new one. Keep it in a password manager. Do not put it in git.

You can make the control token again, and you can make a new Amp provider token in Amp → Settings → Orbs. See [Rotate the Amp provider token](/docs/guides/rotate-token/).

## Recommended way: a private git repo

Run `git init` in the project folder and push it to a private repo. The `.gitignore` that `init` writes is already set up for this:

- `.cf-orbs/control-token` is ignored.
- `.cf-orbs/*` is ignored, so the generated files stay out. The one exception is `.cf-orbs/state.json`, which is not ignored. It holds no tokens.
- In a Workers Builds project (`init --no-deploy`), the repo holds the generated files. Git ignores `.cf-orbs/control-token` and `.cf-orbs/state.json`.

Commit after each `upgrade`, config change or toolchain change. In a Workers Builds project, run `cf-orbs doctor` to check the ignore lines.

## Restore on a new machine

> **Caution**
>
> These steps are worked out from the code. They are not tested on a live account, and the steps marked untested were not run.

1. **Get the files**

   Clone your repo, or copy `cf-orbs.config.jsonc` and `image/` into a new folder.
2. **Log in to Cloudflare**

   Run `npx wrangler login` with the same account. If the login has more than one account, you must pass `--account-id`.
3. **Run init with the same names**

   Put the Amp provider token in a file with mode 600, then run:

   ```sh
   npx cf-orbs init --adopt --token-file <file> --provider-name <name from Amp>
   ```

   The Worker name comes from `name` in your config. If the folder is new and has no config, add `--name <worker>`.

   You need `--adopt` because the Worker already exists and this folder didn't create it. Without it, `init` stops. With it, `init` takes over the Worker: it makes a new control token, sets it on the Worker, and deploys this folder's config and `image/`. The old folder, if it still exists, loses CLI access.

   If your backup has `.cf-orbs/control-token`, copy it into the new folder first (mode 600). Then `init` keeps that token and you don't need `--adopt`.
4. **Check**

   Run `npx cf-orbs doctor` and `npx cf-orbs status`.

### What init does in this case

Verified in the code and in a test with a fake wrangler:

- A new folder has no `.cf-orbs/state.json` URL and no `.cf-orbs/control-token`. Before it makes a token or deploys, `init` runs `wrangler deployments list --json --name <name>`. If the Worker exists, `init` stops with `Worker <name> already exists in this account and this folder did not create it`. `--adopt` skips the stop and prints one warning. If wrangler cannot answer (network, login), `init` prints a warning and goes on.
- Without `.cf-orbs/control-token`, `init` makes a new control token and sets it as `CONTROL_TOKEN` on the Worker at deploy. The old token stops working.
- Without `.cf-orbs/state.json`, the CLI knows no Worker URL, so the token prompt can't offer "keep the current one". In a non-interactive run, `init` stops with `no Amp provider token given` unless you pass `--token-file` or set `AMP_ORB_PROVIDER_TOKEN`. Make a new token in Amp if you do not have the old one.
- The provider name is not saved. Without `--provider-name`, `init` uses `cloudflare` and warns. The name is for display and for the `amp` command; the Worker doesn't use it.
- With `--adopt`, `init` runs `wrangler deploy` for the Worker name in the config. The generated config declares the same Durable Object classes and no migration. A deploy with the same name and account updates the same Worker.
- With no config, `init` writes the defaults (4 vCPU, 12 GiB, 20 GB disk, the pinned Amp image). A running Worker then gets these defaults, not your old settings.
- Old image keys are not in the new folder. A start that needs a missing key fails with `Failed: image key <key> is not deployed — fix: run cf-orbs deploy`.

Untested on a live account:

- That the Durable Object data (orbs, registry, snapshots) is kept after `init` from an empty folder.
- That a paused orb restores after this deploy with the default image.
- Whether a restore of an orb disk needs the old image key.

Until you've tested it yourself, treat the backup of the config and `image/` as the safe path.

Source: https://cf-orbs-site.mdick85.workers.dev/docs/guides/back-up-and-restore/index.mdx