Skip to main content
Experimental version.This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the latest stable version here.
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 the image is unreachable, the orchestrator falls back to the default runner image automatically. 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 SESSION_IMAGE) is forwarded as the workflow’s runner_image input, if either is 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.