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 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.
This mechanism only applies to the fly-machines execution mode. GitHub Actions runs use the ubuntu-latest runner provided by GitHub and are not affected by .ai-implement/image.yml.
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.