Use

Agent images

Each agent runs from its own image, built on your machine from a Dockerfile we publish. The agent version is pinned in that file. We do not ship agent binaries.

Why an image per agent

The sandbox's default image is a minimal Linux with no agent installed, and the runtime starts sandboxes from images, not from Dockerfiles. So each agent needs an image with the agent, the tools it calls, and nothing from your machine. Building it locally means the agent comes from its vendor's own package, under its own license, and not from a copy we redistribute.

Build and rebuild

fenzi run builds the image the first time you start that agent. To build it ahead of time, or rebuild it after an update:

Fenzi uses the one the gateway's driver uses: Podman when the gateway runs sandboxes with Podman, Docker otherwise, and the other one if that is not installed. It needs one of them even when sandboxes run on the MicroVM driver, which finds the image in your local Docker or Podman before it pulls anything.

After a rebuild, start a new sandbox. The sandbox remembers each program the first time it connects, and blocks it if the file at that path changes, so a running sandbox does not pick up a new agent binary.

What is in the image

Every image creates an unprivileged sandbox user, sets the working folder to /sandbox, and turns off npm audit, which sends a POST that a read-only registry rule would block.

Run fenzi agents to see the versions your CLI pins.

Why the real path matters

Network rules name the programs allowed to use them, and the sandbox matches the path the kernel resolves, not the name you type. For Claude Code, claude resolves to a native binary inside the npm package, so that path is what the rule names. Codex's codex command is a Node script that starts a native program for your processor, and that program makes the calls, so its rule names the native program for Arm and for x86. OpenCode's command is itself that native program, at bin/opencode.exe inside the npm package, on Arm and on x86. Grok's command is a link to bin/grok-native in the same kind of package. The catalog records these paths per version, which is why agent versions are pinned and not floating.

The base image tag, node:22-bookworm-slim, is not pinned, so a rebuild can change files even when the agent version stays the same. Once a week, and on every change to the catalog, CI builds each image from its Dockerfile for linux/amd64 and linux/arm64, the Arm build under emulation. Inside each image, as the sandbox user and without network, it checks every path the entry lists for that processor: the file exists, it is its own real path and not a link, the user can run it, and it is a Linux program for that processor. A path that names a processor, such as Codex's two, is checked only on that processor. Any failure fails the run. Nothing is pushed to a registry. The script is agents/check-images.sh in the open-source repository, and it runs on any machine with Docker.

Adding tools to an image

The images carry what an agent needs for ordinary work in a JavaScript or Python project. If your project needs another toolchain, install it inside the sandbox from a registry the policy allows, or ask for the host it downloads from. Custom images are not part of the catalog. A tool you add does not get network access of its own unless the agent starts it.

Agent updates

Agents cannot update themselves inside the sandbox: their update hosts are not in the policy, and Claude Code's auto-update is turned off. A new agent version comes with a new Fenzi release, after the catalog's paths and profile are checked against it. So a vendor's update reaches the sandbox with that release, not on the vendor's release day. See Versions and upgrades.