Upgrade

There are two kinds of upgrade, and they are separate: a new cf-orbs version, and a new Amp orb image.

Upgrade cf-orbs

A new cf-orbs version updates the Worker code, the provider image, and dispatch.sh. Your config and image/Dockerfile don’t change.

Run this in your project directory:

npx cf-orbs@latest deploy

deploy copies the new templates into .cf-orbs/, builds, and deploys. Then it asks the Worker to restart the provider if the provider image changed, and prints one of:

• provider: restarted for the new image
• provider: image unchanged
• provider: started with the new image (it was not running)

After that it starts the prewarm instances. Your paused orbs survive.

If the provider Durable Object still runs code from a cf-orbs version that has no provider restart, deploy waits for it to unload. This can take up to about 7.5 min. The 5-min check then starts the provider.

In a Workers Builds project, run npx cf-orbs init --no-deploy, then commit and push. See Install with Workers Builds.

Move to a new Amp orb image

Use upgrade when Amp publishes a new orb image. You need the new digest, in the form sha256:<64 hex>. Amp publishes it; cf-orbs doesn’t track digests or look for new ones.

To see the digest you use now, read the FROM line in image/Dockerfile. After an upgrade, the config key ampImageDigest holds the same digest.

npx cf-orbs upgrade --digest sha256:<hex>

upgrade does this:

1. Changes the FROM line in image/Dockerfile to the new digest.
2. Keeps the old image buildable under a new key orb-<short>. It writes image/orb-<short>.Dockerfile and adds an entry to images in the config. The <short> is the first 12 hex characters of the old digest.
3. Sets ampImageDigest in the config.
4. Runs a deploy, the provider restart check, and prewarm.
5. Prints the cache steps below.

If the Dockerfile already uses the digest, upgrade prints image/Dockerfile already uses <digest>; nothing to do.

The upgrade command also prints two warnings:

• paused orbs may not restore after upgrade (their snapshots name image key orb, which is now the new image); push or commit their work first
• Awake orbs keep the old Worker code until they pause. Keep the old key until their snapshots expire (30 days).

The first warning is more cautious than the test results. On a live install, a paused orb restored after cf-orbs deploy pushed a new image digest, and the restored disk kept its old content. New image content reaches only orbs that start from the image. If a snapshot is missing, the orb starts from the image and Amp sets the repo up again.

Skip the deploy

npx cf-orbs upgrade --digest sha256:<hex> --no-deploy

This edits the files but doesn’t deploy, so run cf-orbs deploy yourself. In a Workers Builds project, --no-deploy also writes .cf-orbs/wrangler.jsonc; commit and push it.

Clear the caches

Amp caches one project snapshot for each provider for 72 hours. After an image or setup change, new threads can still start from a disk made with the old image. To avoid that, clear both caches:

1. In Amp, delete the cached snapshot in Orb Settings → Snapshots, or run amp projects snapshots delete <owner/repo> --resource <size>.

2. In cf-orbs, run:

   npx cf-orbs snapshots forget --all-project

Do the same after a change to a repo’s .agents/setup.

Pin and reproducibility

Always keep a digest in FROM, never :latest. See Orb image.

upgrade writes image/Dockerfile, a new image/<key>.Dockerfile and the config, so commit them. See Back up and restore.