Sandbox

The sandbox is the core of agentfile. It defines the container environment the agent runs in and is required for all workflows.

Rootless Podman is used as the container runtime by default. Docker is supported as a fallback.

Configuration

All sandbox configuration lives under the sandbox key in agentfile.yaml. Run agentfile init to generate a file from the default template.

sandbox:
  image:
    repository: fedora
    tag: latest

  packages:
    - curl
    - git
    - kubectl
    - helm

  agents:
    - goose
    - opencode

`sandbox.image`

Field	Type	Required	Description
`repository`	string	yes	Container image repository (used as the base image)
`tag`	string	no	Image tag (defaults to `latest`)

Examples of repository values: fedora, ubuntu, alpine, docker.io/library/debian, ghcr.io/org/custom-base.

`sandbox.packages`

A list of packages to install using the base image's native package manager. The tool auto-detects which package manager is available in the image (supports dnf, apt-get, apk, pacman, and zypper).

`sandbox.agents`

A list of agent binaries to install from upstream GitHub releases. Supported values: goose, opencode.

If the field is omitted entirely, both goose and opencode are installed by default. Set to an empty list (agents: []) to skip agent installation.

The agent to run is selected at runtime with agentfile run -a <name> (defaults to opencode).

Initialize an agentfile.yaml

Run agentfile init in any project directory to create an agentfile.yaml with the default sandbox template:

cd my-project/
agentfile init

Edit the generated file to customize installed packages and agents.

Build the container image

agentfile build

This finds the nearest agentfile.yaml (searching upward from the current directory) and builds a container image tagged agent-<directory>-<sha256hash>. The tag changes whenever the agentfile.yaml content changes.

Run the sandbox

agentfile run

This launches an interactive container session with:

The current directory mounted at /code
Agent-specific config directories bind-mounted from the host
no-new-privileges security option

If the image does not exist locally, it is built automatically before running.

The following flags are supported:

Flag	Default	Description
`-a`/`--agent`	`opencode`	Agent to run (`goose`, `opencode`)
`-c`/`--cpus`	`1`	CPU limit; pass `0` for no limit
`-m`/`--memory`	`2G`	Memory limit; pass `0` for no limit
`-e`/`--entrypoint`	agent default	Override the agent entrypoint
`--minikube`	`false`	Mount a filtered minikube kubeconfig as `/root/.kube/config`
`--minikube-kubeconfig`	auto-generated	Path to a pre-filtered kubeconfig (skips auto-generation)
`--ssh`	—	Grant SSH access to a remote machine (`user@host`)
`--ssh-key`	—	Path to SSH private key on the host

agentfile run -a goose -- --verbose
agentfile run -c 4 -m 8G