---
title: "Add toolchains to the orb image"
description: "Put compilers and tools in every orb, test the image, and clear the snapshot caches."
---

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

# Add toolchains to the orb image

Edit `image/Dockerfile` to put a compiler or tool in every orb. Setup that belongs to one repo goes in that repo's `.agents/setup` instead.

1. **Add RUN lines**

   Put them between `USER root` and `USER user`:

   ```dockerfile
   RUN apt-get update \
    && apt-get install -y --no-install-recommends golang-go \
    && rm -rf /var/lib/apt/lists/*
   ```

   Pin versions where you can (`pkg=<version>`), because a rebuild with unpinned packages can give a different image.
2. **Test the image locally (optional)**

   ```sh
   docker build --platform linux/amd64 -t cf-orbs-orb:dev image/
   docker run --rm cf-orbs-orb:dev bash -lc 'ps -o args= -p 1; id -u; amp --version'
   ```

   You should see `/usr/bin/tini -s -- sleep infinity`, `1000`, and an amp version.
3. **Deploy**

   ```sh
   npx cf-orbs deploy
   ```

   The first image push is about 1.8 GB. `deploy` retries registry timeouts and `Unauthorized` answers up to 3 times. If it still fails, run `cf-orbs deploy` again: the registry keeps the layers it already received.
4. **Clear the snapshot 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:

      ```sh
      npx cf-orbs snapshots forget --all-project
      ```

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

Keep the rules in [Orb image](/docs/concepts/orb-image/): user `user`, `sudo`, the `tini` entrypoint, and the digest pin in `FROM`. `cf-orbs doctor` fails if a `FROM` has no digest.

Commit `image/` after each change. See [Back up and restore](/docs/guides/back-up-and-restore/).

Source: https://cf-orbs-site.mdick85.workers.dev/docs/guides/add-toolchains/index.mdx