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.

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

Get the files
Clone your repo, or copy cf-orbs.config.jsonc and image/ into a new folder.
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.
Run init with the same names
Put the Amp provider token in a file with mode 600, then run:
```
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.
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.