Skip to main content
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

Bring your toolchain

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.

Pull from your registry

Any public or private OCI registry: GitHub Container Registry, Docker Hub, Azure Container Registry, GitLab, Quay, Artifactory, and others.

Pinned by digest

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.

Selected per repository

Images are workspace-level. Each repository picks one, or keeps the default. See Repository Agent Image for the repository setting.

​
System and workspace images

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. 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 and let workflows inject them at run time.

​
Registering an image

Open Agent Images

Select Agent Images in the workspace sidebar, then click Register image.

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

Enter the image reference

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.

Choose registry access

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.

Save

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

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