--- title: "Upgrade" description: "Move to a new cf-orbs version or a new Amp orb image digest." --- > 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. # 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: ```sh 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](/docs/guides/install-workers-builds/#upgrades). ## 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. ```sh npx cf-orbs upgrade --digest sha256: ``` `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-`. It writes `image/orb-.Dockerfile` and adds an entry to `images` in the config. The `` 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 ; 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 ```sh npx cf-orbs upgrade --digest sha256: --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 --resource `. 2. In cf-orbs, run: ```sh 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](/docs/concepts/orb-image/). `upgrade` writes `image/Dockerfile`, a new `image/.Dockerfile` and the config, so commit them. See [Back up and restore](/docs/guides/back-up-and-restore/). Source: https://cf-orbs-site.mdick85.workers.dev/docs/guides/upgrade/index.mdx