Container execution

Container-backed tools let agents run commands without relying directly on the host shell. They are powerful tools, so the important distinction is whether the current project is mounted read-write.

Tool inventory

sandbox_exec

Use sandbox_exec for experiments that do not need to mutate the project checkout:

• calculations
• quick scripts
• dependency-free repros
• testing an idea before touching files

The sandbox has its own workspace. It is useful when the answer needs command execution but not project writes.

chroot_exec

Use chroot_exec when commands need the project mounted inside the container:

/chroot

The mount is read-write. That makes chroot_exec appropriate for project checks, tests, builds, and intentional edits produced by commands. It also means destructive commands can damage the checkout.

Treat chroot_exec as a high-power tool:

• inspect before changing
• avoid destructive bulk operations without a dry run
• keep generated files and secrets out of Git
• prefer normal project validation commands over broad custom scripts

Runtime helper lifecycle

The plugin uses bundled container definitions by default. They can be overridden only through trusted global configuration via paths.containersDir.

Helper images are versioned from the active container definition. When that definition changes, the next invocation builds a new managed image revision. Older managed revisions can be pruned after successful builds when they are no longer used.

Persistent helper containers use plugin ownership labels and idle leases. Cleanup is opportunistic during later tool invocations; unused helper containers become eligible after the configured idle window.

When to use what