Orb image | cf-orbs

Every orb starts from one image.

image/Dockerfile builds that image. It’s the Amp orb image, pinned by digest (the image’s exact sha256 hash, not a tag). It adds tini (a small init program) as PID 1 and sleep infinity as the command. cf-orbs deploy builds it and stores it under the image key orb.

cf-orbs init writes image/Dockerfile once and never overwrites it, so you can edit it. See Add toolchains.

What cf-orbs needs from the image

Keep these when you change the file:

FROM an Amp orb image, or an image that meets Amp’s bring-your-own-image rules.
User user, uid 1000, HOME /home/user, and passwordless sudo.
amp, bash, sudo, hostname, setsid, flock, ps, pgrep, sha256sum and stat on PATH.
localhost in /etc/hosts. The bootstrap runs sudo hostname localhost, because /etc/hosts is read-only after a snapshot restore.
ENTRYPOINT ["/usr/bin/tini", "-s", "--"] and CMD ["sleep", "infinity"]. Without an init that reaps, stopped amp processes stay as zombies, and without a long-running command, the container exits.
Platform linux/amd64. Cloudflare Containers run amd64 only.

Snapshots and the image

A snapshot holds the disk changes on top of the image it came from. That’s why the image matters for paused orbs:

Never use a tag such as :latest in FROM. Keep the digest pin.
A change to image/Dockerfile gives a new image under the same key orb. Paused orbs still restore, and a restored disk keeps its old content. New image content reaches only orbs that start from the image.
Don’t remove an image key while a snapshot that uses it is younger than 30 days.
To move to a newer Amp orb image, run cf-orbs upgrade --digest sha256:<new>. See Upgrade.
Amp project snapshots can hold a disk made with an old image, so clear the caches after an image change. See Manage snapshots.

Extra image keys

The images config key maps an ORB_IMAGE reference to an image key. An image key <key> builds from image/<key>.Dockerfile. The default Amp image always maps to the key orb, and cf-orbs upgrade adds old keys here.

The keys orb and provider are reserved. A key must match ^[a-z0-9][a-z0-9_-]{0,62}$.

If a job names an Amp image digest that differs from the pinned one, cf-orbs uses the pinned orb image and logs a note.

Project-specific setup

Setup for one repo belongs in that repo’s .agents/setup. Amp runs it when an orb starts, and project snapshots keep the result.

The provider image

The provider image is a separate image, built from provider/Dockerfile: a node:24-bookworm-slim base pinned by digest, a pinned @ampcode/cli, curl and tini. It’s a template in the CLI, and you don’t edit it. cf-orbs doctor checks that its FROM is pinned by digest.