> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Images
> Register container images from your own registry so agents build and test with the exact toolchain your repositories need.
An agent image is the container your agents run in. Cloning, builds, tests, `script.run` steps, and stdio MCP servers all execute inside it. Overcut ships two system images that cover common stacks. When a repository needs something they lack (Rust, Bazel, a pinned SDK, an internal CLI), you register an image from your own registry on the **Agent Images** page and select it for that repository.
Open **Agent Images** from the workspace sidebar, under **Agent Runtime**.
Registering custom images is an Enterprise feature. On other plans the page describes the feature and offers **Get access to custom images**. System images are available on every plan.
***
## How it works
Build the image with the SDKs, compilers, and CLIs your repositories need. Overcut adds its own runtime at run start, so nothing Overcut-specific goes into the image.
Any public or private OCI registry: GitHub Container Registry, Docker Hub, Azure Container Registry, GitLab, Quay, Artifactory, and others.
Overcut resolves the tag to a digest once at registration. Every run uses that digest, even if the tag moves upstream. You choose when to pick up a new build.
Images are workspace-level. Each repository picks one, or keeps the default. See [Repository Agent Image](/docs/repositories/agent-image) for the repository setting.
***
## System and workspace images
| Kind | Who maintains it | Where it appears |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **System images** | Overcut. **Universal 2** (the default) and **Universal 6** are based on Microsoft's dev container universal image and ship Python, Node.js, Java, Go, Ruby, PHP, and .NET. | In every repository's **Agent Image** picker under **System images**. They are not listed on the Agent Images page and cannot be edited. |
| **Workspace images** | You. Registered from a registry you control and visible only to your workspace. | On the Agent Images page, and in the repository picker under **Workspace images** once they are **Ready**. |
Toolchain first, image second. If a repository only needs a newer version of a language the default image already ships, select **Universal 6** instead of registering a custom image. Custom images are for toolchains the universal images lack.
Custom images are also not a substitute for [Repository Caching](/docs/repositories/repository-caching). Put SDKs, compilers, system packages, and private CLIs in the image. Leave `npm install` and similar dependency installs to the cache.
***
## Image requirements
Overcut copies your image into its own registry and checks it before making it selectable. The image must:
* Be built for **linux/amd64**. Multi-architecture images are fine; Overcut picks the amd64 variant.
* Be at most **4 GiB compressed**.
* Include `bash` and `git`.
* Have a writable `/tmp`. Every standard base image does; only minimal images built from `scratch` lack it.
* Use a **glibc** userland with `libstdc++` (Debian, Ubuntu, RHEL, and similar). Alpine and other musl-based images, and `scratch` images, fail the check.
* Work when run as a non-root user. Overcut runs every image as a fixed non-root user, ignoring the image's own `USER`, so toolchains must be runnable by a non-root user. Anything that only works as root (a tool installed with root-only permissions, an SDK that writes to its install directory) fails at run time.
Nothing else is required. Overcut sets the home directory on a writable volume it mounts, so the image needs no user account or home. At run start it mounts its own runtime into the container, which is why glibc and `libstdc++` must be present.
Never bake tokens or secrets into an image. Image layers are permanent. Store credentials in the [Vault](/docs/reference/vault) and let workflows inject them at run time.
***
## Registering an image
Select **Agent Images** in the workspace sidebar, then click **Register image**.
Enter a **Name**. It is shown in the repository image picker and must be unique in the workspace. Add an optional **Description** so teammates know what the image ships.
In **Image reference**, enter the full `registry/repository:tag`, in lowercase, for example `ghcr.io/acme/runner:1.2`. Docker Hub images can omit the registry host.
Under **Registry access**, leave **Credential** at **None (public image)** for a public image. For a private image, pick an existing credential for that registry host or click **New credential** to add one. See [Registry credentials](#registry-credentials).
Click Save. Overcut resolves the digest, copies the image, and runs the compatibility check in the background. The image detail page opens and updates as registration progresses.
Registration takes from seconds to a few minutes depending on image size. The image becomes selectable in repository settings once its status is **Ready**.
### Registry credentials
Private images need a credential for their registry. The credential's **Registry host** must match the host in the image reference (`ghcr.io` for `ghcr.io/acme/runner:1.2`, `docker.io` for Docker Hub).
Click **New credential** in the register form to open the **New registry credential** dialog and fill in:
| Field | Value |
| --------------------- | ---------------------------------------------------------------- |
| **Name** | A label such as `ghcr read token`. |
| **Registry host** | Pre-filled from the image reference. |
| **Username** | The registry username, or the account name the token belongs to. |
| **Password or token** | A read-only token or password for the registry. |
Use a token with pull-only permissions. The value is stored encrypted, sent to the registry only during registration and refresh, and never shown again. To rotate a token, create a new credential and select it on the image; saving registers the image again with the new credential.
Registry credentials are separate from the Vault. They authenticate Overcut to your registry when it copies the image, and are never available to agents or workflows.
***
## Image status
Each image shows a status on the Agent Images list and on its detail page, with a message under **Details** that explains the current step or the failure reason.
| Status | Meaning |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pending** | Overcut is resolving the image digest and size from your registry. |
| **Importing** | The digest is known. The image is being copied and checked for compatibility. |
| **Ready** | The image is selectable by repositories. Runs use the digest shown on the detail page. |
| **Failed** | Registration failed. The details column shows why: authentication (401 or 403), image not found, too large, or a list of failed compatibility checks. The image cannot be selected. |
| **Disabled** | A user deactivated the image. It cannot be selected, and runs on repositories that still select it fail until you activate it again or switch them. |
The detail page also shows the pinned **Digest**, **Size (compressed)**, where runs pull the copy from (**Runs from**), and when it was **Registered**.
### Refreshing and retrying
Runs stay pinned to the digest resolved at registration. When you push a new build to the same tag, click **Refresh** on the image detail page:
* If the tag now points at a new digest, Overcut registers the new build while the current digest keeps serving runs. The status message shows **Refreshing** until the swap completes.
* If nothing changed, the message shows **Up to date**.
* If the new build fails registration, the message starts with **Refresh failed** and the previous digest stays in use.
On a **Failed** image the same button reads **Retry**. Use it after fixing the reference, the credential, or the image itself.
### Editing an image
Open the image and change any field, then Save:
* Changing the **Name** or **Description** takes effect immediately and does not affect runs.
* Changing the **Image reference** or the **Credential** registers the image again. A Ready image keeps running on its current digest until the new copy is ready. A Failed image restarts its registration.
Refresh, Retry, and Save are unavailable while a registration is in progress. Refresh is also unavailable on a Disabled image; activate it first.
### Deactivating and deleting
* **Deactivate** a Ready image with the activation toggle next to its name on the detail page. Repositories can no longer select it, and runs on repositories that still select it fail at preparation. Click the toggle again to activate it. The toggle is only shown for Ready and Disabled images.
* **Delete** removes the image from the workspace. The button is unavailable while a registration is in progress or while any repository selects the image; the tooltip tells you how many. Switch those repositories to another image first. Runs already in progress are not affected.
***
## Selecting an image for a repository
Images apply per repository. Open the repository's settings, and in the **Agent Image** section pick from **Default Image**, **System images**, or **Workspace images**. Only Ready, active workspace images appear. The choice applies from the next run.
For ticket repositories (Jira, Azure DevOps boards), set the image on the linked **code** repository: that is where agents build and test. Resolution order and conflict handling are covered in [Repository Agent Image](/docs/repositories/agent-image#how-overcut-selects-the-image-for-a-run).
After switching a repository to a new image, run one of its workflows from the Playground to confirm builds and tests pass in the new environment before relying on it in production.
***
## Plan limits
Custom images require an Enterprise plan and count against a per-workspace quota. Pending, Importing, and Ready images count toward it; Failed and Disabled images do not, so a broken registration never blocks a retry. When you hit the limit, registering shows **Your current plan allows up to N custom agent images**. Delete or deactivate images you no longer use, or contact Overcut to raise the limit.
***
## Troubleshooting
| Symptom | Cause | Fix |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Image **Failed**, details mention 401, 403, unauthorized, or denied | Private image without a credential, wrong credential, or a credential whose registry host does not match the reference | Select the right credential on the image (or create one) and Save, or click **Retry** after fixing it |
| Image **Failed**, details mention not found or manifest unknown | Wrong repository or tag, or no linux/amd64 variant published | Correct the **Image reference** and Save |
| Image **Failed**, details mention size or larger than | Image exceeds 4 GiB compressed | Slim the image (multi-stage build, drop package caches), push, then **Retry** |
| Image **Failed**, details list bash, git, glibc, libstdc++, or /tmp | The image does not meet the [requirements](#image-requirements); typically an Alpine or scratch base | Rebuild on a glibc base with the listed items, push, then **Retry** |
| Register shows **Your current plan does not allow custom agent images** | The workspace plan does not include custom images | Click **Get access to custom images** on the Agent Images page |
| Run fails at preparation with **Agent image ... is not available: status is Disabled** (or Failed) | The repository selects an image that is no longer Ready | Activate or Retry the image, or switch the repository to another image |
| Run fails at preparation with **image pull failed** | The image copy could not be pulled | Click **Refresh** to re-check the source, and confirm the image still exists in your registry |
| Run fails at preparation with **agent image ... is incompatible** | The image passed registration but cannot run Overcut's injected runtime | Rebuild on a glibc base with `libstdc++`, push, then **Refresh** |
| A build or test step fails with `command not found` for a language or tool | The repository runs on an image without that toolchain | Select **Universal 6** or register a custom image, then select it for the repository |
***
## Chat
Overcut chat can list images and their status, register an image from a reference you provide, refresh or retry a registration, activate or deactivate an image, and select an image for a repository. It never asks for registry passwords: create credentials on the Agent Images page and chat can attach an existing one. Deleting images stays in the UI. See [Chat with Overcut](/docs/how-to/chat-with-overcut).
***
## Related
* [Repository Agent Image](/docs/repositories/agent-image): the per-repository setting and how a run resolves its image
* [Repository Caching](/docs/repositories/repository-caching): speed up dependency installs without changing the image
* [Private Package Registries](/docs/quick-starts/private-package-registries): bake registry configuration into a custom image
* [Vault](/docs/reference/vault): where credentials for workflows belong