---
title: "Orb image"
description: "The image every orb starts from, why it is pinned by digest, and how snapshots depend on it."
---

> 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.

# Orb image

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](/docs/guides/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](https://ampcode.com/docs/orbs/self-hosted#bring-your-own-image).
- 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](/docs/guides/upgrade/).
- Amp project snapshots can hold a disk made with an old image, so clear the caches after an image change. See [Manage snapshots](/docs/guides/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.

Source: https://cf-orbs-site.mdick85.workers.dev/docs/concepts/orb-image/index.mdx