Skip to main content
If your repo needs tools or language runtimes that aren’t in the default runner image, you can point AI-Implement at a custom image by committing .ai-implement/image.yml to the default branch of your target repo. When AI-Implement starts a session for your repo, it reads this file and boots the Fly Machine using your image instead of the default.

​
How it works

Create a file at .ai-implement/image.yml in the default branch of your target repo:
The image must be publicly pullable. AI-Implement does not manage credentials for private registries. If the file is absent, malformed, or its image: value isn’t a well-formed image reference, the orchestrator falls back to the default runner image automatically — but that check only looks at the file itself. A syntactically valid reference that can’t actually be pulled (private, deleted, wrong tag) passes this check and fails later, when the session tries to start, with a manifest/unauthorized error.
The file is always read from the default branch, never from a pull request’s head — so editing image.yml in an open PR won’t change which image that PR’s runs use. Merge the change first.
The default base image is:

​
Building a custom image

Build your image FROM the published base image so you inherit all the tools and configuration the default runner provides. Then add whatever your repo needs on top:

​
Setup steps

1

Create a Dockerfile

Start from the base image and add the tools or runtimes your repo requires.
2

Build and push to a public registry

Build the image and push it to a registry where it can be pulled without authentication. GitHub Container Registry (ghcr.io) is a common choice.
3

Commit .ai-implement/image.yml

Create the file in your target repo pointing at the image you just pushed:
Commit this to your default branch. AI-Implement reads it from there on the next run.
.ai-implement/image.yml works for both execution modes.
  • In Fly Machines mode, the orchestrator boots the session machine directly on your image.
  • In GitHub Actions mode, the orchestrator forwards your image to claude-implement.yml as the container.image for the workflow job.
Common use cases for a custom runner image include repos that need Terraform, Ruby, Go, or a specific language version that isn’t available in the default image.

​
Alternative: GitHub Actions variable

Repos using GitHub Actions execution mode have a second image-override mechanism: the AI_IMPLEMENT_RUNNER_IMAGE repository variable. When set, the synced claude-implement.yml workflow uses that image as the container for its job.
Resolution order when the orchestrator dispatches a GHA-mode run:
  1. The orchestrator’s resolved image (from .ai-implement/image.yml or its own AI_IMPLEMENT_RUNNER_IMAGE — the deprecated SESSION_IMAGE env var name is still honored as a fallback) is forwarded as the workflow’s runner_image input, if either is explicitly set
  2. Otherwise the workflow falls back to AI_IMPLEMENT_RUNNER_IMAGE if that variable is set
  3. Otherwise the built-in default (ghcr.io/builddownai/ai-implement-runner:latest) is used
Most repos use .ai-implement/image.yml because it gives you one mechanism for both execution modes. Reach for AI_IMPLEMENT_RUNNER_IMAGE when you want an org-level default that applies across all your repos without committing a file to each one.