Agent image: the toolchain coding agents run on

Why the toolchain matters

Editing a Rust service needs cargo, and working on a Flutter app needs the Flutter SDK. The Docker image a repository runs on decides which compilers, package managers and runtimes exist, both for the coding agent's container and for the build and test gates. A missing tool then shows up as a build environment problem, which DevFlow reports instead of asking for a code fix.

What the universal default contains

Most repositories run on devflow/agent-universal:stable, which is built on Debian bookworm for many languages at once. It pins Node 22 with corepack for pnpm and Yarn, Python 3.11, Go 1.25, PHP 8.2 with Composer, the .NET 9 SDK, stable Rust through rustup, and OpenJDK 17 with Maven.

It runs as any non-root user. Every cache resolves under $HOME, which is a tmpfs inside each container, so nothing is written into the filesystem layers at run time.

Resolution order

For the coding container, DevFlow picks per repository in three steps:

1. the image the workspace owner confirmed, which must come from an allowlisted registry;
2. otherwise the decider's pick from DevFlow's catalog;
3. otherwise the universal default.

The decider

Before planning creates worktrees, DevFlow makes one model call per repository that lacks an owner's confirmation. DevFlow pays for that call itself, through an internal OpenRouter key, and the decider is off when the operator leaves that key unset.

The answer must fit a strict schema whose only allowed values are catalog entries present on the host. DevFlow stores it with its reason, confidence, token count and cost, and decides again only when the repository's signals change or an owner asks.

The catalog

Besides the universal default, the catalog holds devflow/flutter:stable, which packages the Flutter SDK to run as a non-root user; the stock upstream Flutter image is root-owned and cannot run under the container's user.

A Flutter repository that pins a release in .fvmrc or .flutter-version runs on a matching versioned image when the operator has built it, and falls back to the stable one with a warning otherwise. When a project then needs a newer Dart SDK than it gets, DevFlow reports a build environment error, because lowering the project's SDK floor would be the wrong fix.

Built locally

DevFlow's own images, the universal default and the Flutter one, are built on the host with ops/build-agent-images.sh, not pulled from a registry. The OpenCode binary and its entrypoint live in a separate runtime volume mounted into every container, so swapping a toolchain never changes the CLI version.

In Workspace Settings → Repositories → Agent image, an owner sets the value directly, or accepts, edits or dismisses an image that DevFlow's preflight detector proposed for the repository. The value is checked against the allowlist before it is saved, and an error in the decider never fails a task.