D-205 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

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

Boundlane uses Docker if it is installed, then Podman. 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 boundlane 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.

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 Boundlane release, after the catalog's paths and profile are checked against it. See Versions and upgrades.