AgentBox

AgentBox is a customizable, policy-driven sandbox for AI coding tools such as Claude Code, Codex, Gemini CLI, and OpenCode.

It starts from a safer default posture and exposes only the files, networks, toolchains, and local services that a project actually needs.

agentbox claude
agentbox codex
agentbox gemini
agentbox opencode

What AgentBox Is

AgentBox is:

• a per-project runtime for AI coding tools
• an operator-controlled capability broker
• a practical local containment layer for real development workflows

AgentBox is designed for cases like:

• fully local, air-gapped work with Ollama and OpenCode
• restricted Claude/Codex access to selected documentation or API domains
• local Docker homelab access through explicit Docker networks
• project-specific toolchains installed through .agentbox/Dockerfile
• hiding .env, keys, deploy credentials, and similar sensitive files from the tool

What AgentBox Is Not

AgentBox is not:

• a virtual machine
• a hostile-code-proof isolation guarantee
• a general-purpose devcontainer platform
• a secret manager
• an agent orchestration framework
• a system that should let the agent freely widen its own sandbox by default

Why It Exists

AI coding tools are useful because they can inspect, edit, run, and connect. That is also where the risk comes from.

AgentBox exists to let you:

• hide sensitive files from the tool
• run fully air-gapped when needed
• allow only specific public sites when needed
• reach local project services through explicit Docker networks
• provide exactly the CLIs and toolchains a project needs inside the container
• keep the trust level of the session visible and explicit

Core Use Cases

1. Local-only with Ollama and OpenCode

• no public internet
• local model/runtime only
• optional local Docker network reachability

Example:

docker_networks = ["ollama_default"]

[env]
OLLAMA_HOST = "http://ollama:11434"

2. Restricted Claude/Codex with local lab services

• public internet only to approved domains
• local Docker homelab reachable via explicit docker_networks
• project image can include php, composer, npm, nvm, dig, etc.

Example:

allow_hosts = ["api.anthropic.com", "github.com", "*.npmjs.org"]
docker_networks = ["cherrylab"]
exclude = [".env", ".env.*", "secrets/"]

3. Project-specific toolchains without extra platform exposure

• Go, Rust, PHP, Node, or other toolchains installed through .agentbox/Dockerfile
• no Docker socket unless explicitly required
• no unnecessary local-service access

Example:

# .agentbox/Dockerfile
ARG BASE_IMAGE
FROM ${BASE_IMAGE}

RUN apt-get update && apt-get install -y --no-install-recommends golang \
    && rm -rf /var/lib/apt/lists/*

Trust Levels

Every session is classified and displayed at startup.

Level	Meaning
airgapped	No public internet and no Docker socket
restricted	Public internet limited to explicit host/domain rules
open	Public internet unrestricted
softened	Docker socket mounted; this is a real containment downgrade

softened always wins over other classifications.

Security Model

AgentBox uses multiple layers:

Layer	Responsibility
Docker	Outer runtime, image packaging, local network attachment
agentbox-launch	Trusted in-container launcher
bwrap	Final process-visible filesystem sandbox
Proxy + firewall	Restricted public internet policy
Trust banner	Honest startup classification for the current session

Important limitations

• AgentBox is a practical containment layer, not a VM-grade security boundary.
• Hidden paths are currently masked, not magically removed from the namespace.
• Exact hidden paths are strong for the running session.
• Pattern-based excludes are evaluated at session start; newly created matching files may require agentbox reload and a fresh tool launch to be covered.
• docker_socket = true materially weakens containment and is always classified as softened.
• Inner bwrap support currently requires a looser outer Docker security profile so the final sandbox can be created.

Filesystem Policy

AgentBox distinguishes between:

• visible workspace paths
• extra mounts
• hidden paths
• runtime/control-plane paths

Workspace

The project root is mounted into the container and remains the main writable working area.

Extra mounts

Use mounts to expose additional paths:

mounts = [
  "ro:~/work/shared-lib",
  "ro:~/work/docs:/ref/docs",
  "~/work/output:/workspace/output",
  "ro:~/.gitconfig:/home/agentbox/.gitconfig",
]

Format:

[ro:]<src>[:<dst>]

• default is writable
• ro: makes the mount read-only
• omitting :<dst> mirrors the source path inside the container

Hidden paths

Hidden paths are enforced by the final bwrap sandbox, not by removing files from the outer Docker container.

• hidden files are replaced with a read-only empty-file placeholder
• hidden directories are replaced with a read-only empty-directory placeholder
• exact excludes remain protected for the running session
• glob-style excludes are launch-scoped snapshots

That means a newly created file such as .env.local may still need agentbox reload and a fresh tool launch before it becomes hidden.

Use exclude to mask sensitive files or directories:

exclude = [".env", ".env.*", "secrets/", ".git/credentials"]

Current semantics:

• hidden files are masked by overmounting them with a read-only empty file placeholder
• hidden directories are masked by overmounting them with a read-only empty directory placeholder
• the underlying host files are not exposed through those paths
• writes to hidden paths fail against the placeholder instead of modifying the real project path

This means hidden paths are protected, but they are not literally absent from the namespace.

Control-plane paths

AgentBox control files are hidden from the final AI tool view by default:

• .agentbox/
• .agentbox.toml
• launcher/runtime control paths

Network Policy

Public internet policy is independent from local Docker network reachability.

Public internet modes

allow_hosts	Result
[]	air-gapped
explicit hosts/domains	restricted
["*"] or ["all"]	open

Example:

allow_hosts = ["api.anthropic.com", "github.com", "*.npmjs.org"]

Restricted mode

Restricted mode is implemented with:

• an AgentBox-managed proxy sidecar
• deny-by-default firewall rules
• explicit local Docker network allowances

Restricted mode supports:

• exact hostnames
• wildcard domains
• literal IPs

Local Docker networks

Use docker_networks for project or homelab services:

docker_networks = ["myproject_default", "worklab"]

This does not automatically imply public internet access.

Project Customization

AgentBox supports both project-local config files and a project-local Dockerfile.

Config files

~/.config/agentbox/config.toml
.agentbox.toml
.agentbox/config.toml

If both project config files exist, .agentbox/config.toml wins.

Project image

Place a Dockerfile at:

.agentbox/Dockerfile

AgentBox will:

• detect it
• build a project image on demand
• cache it
• rebuild when the Dockerfile or base image changes

The base image is provided through BASE_IMAGE.

Example:

ARG BASE_IMAGE
FROM ${BASE_IMAGE}

RUN apt-get update && apt-get install -y --no-install-recommends \
    php-cli composer \
    && rm -rf /var/lib/apt/lists/*

Configuration

AgentBox uses TOML config.

Common keys

Key	Meaning
image	Base image to run
allow_hosts	Public internet allow rules
docker_networks	Reachable local Docker networks
ssh_agent	Forward host SSH agent
docker_socket	Mount Docker socket
exclude	Hide files or directories
mounts	Extra mounts
path_prepend	Prepend directories to tool PATH
env_files	Pass env files to Docker
[env]	Explicit environment variables
[tool_config]	Tool config directories to mount

Example

exclude = [".env", ".env.*", "secrets/"]
allow_hosts = ["api.anthropic.com", "github.com"]
docker_networks = ["myproject_default"]
path_prepend = ["/usr/local/go/bin"]
ssh_agent = false
docker_socket = false

[env]
GOROOT = "/usr/local/go"

[tool_config]
claude = "~/.claude"
codex = "~/.codex"

Context Injection

AgentBox injects context into supported tool convention files so the tool understands:

• trust level
• network posture
• available mounts
• hidden paths
• key sandbox rules

Current convention files:

File	Tools
CLAUDE.md	Claude Code
AGENTS.md	Codex, OpenCode
GEMINI.md	Gemini CLI

This context is meant to explain the current environment, not to hand control of the sandbox to the agent.

Disable with:

context_injection = false

Commands

Command	Description
agentbox <tool>	Run a supported tool in the project runtime
agentbox shell	Open a shell in the project runtime
agentbox down	Stop the project container
agentbox down --rm	Stop and remove the project container
agentbox ps	List AgentBox containers
agentbox init	Create project config template or export resolved config
agentbox inspect	Show resolved config
agentbox explain	Show effective policy summary
agentbox reload	Refresh launcher-only project state and detect rebuild-required changes
agentbox doctor	Check Docker and image availability
agentbox rebuild	Recreate the project container
agentbox version	Print version

Config flags apply to <tool>, shell, reload, rebuild, inspect, explain, and init --export:

Flag	Description
--name <name>	Override container name
--image <image>	Override image
--ssh-agent[=true|false]	Enable or disable SSH agent forwarding
--docker-socket[=true|false]	Enable or disable Docker socket mount
--context-injection[=true|false]	Enable or disable injected context
--allow <hosts>	Override allowed public hosts/domains
--docker-network <name>	Add reachable Docker network
--exclude <pattern>	Add hidden path pattern
--mount [ro:]<src[:dst]>	Add extra mount
--path-prepend <path>	Prepend PATH entry inside the tool sandbox
--tool <name>	Limit context/tool conventions to selected tools
--tool-config <tool=path>	Mount a tool config directory
--env <KEY=VALUE>	Add env variable
--env-file <path>	Add env file

agentbox init writes a template by default. agentbox init --export writes the fully resolved config that AgentBox would apply after merging defaults, user config, project config, and any provided CLI overrides. The export target is:

• .agentbox.toml by default
• .agentbox/config.toml if .agentbox/ already exists
• .agentbox/config.toml if it already exists

If the target file already exists, AgentBox asks for confirmation. Use --force to overwrite non-interactively.

Reload Versus Rebuild

Use agentbox reload when only launcher-scoped behavior changed, for example:

• exclude
• path_prepend
• env
• tool convention targeting
• context_injection

Use agentbox rebuild when the outer container shape changed, for example:

• image changes
• mounts
• tool_config
• docker_socket
• ssh_agent
• docker_networks
• public network mode changes

agentbox reload updates future tool launches. It does not mutate an already running tool process in place. agentbox rebuild recreates the project container from the current image. If you changed packaging/Dockerfile or need newer bundled tool CLIs such as Claude Code or Codex, rebuild the base image first with make image, then run agentbox rebuild.

Export Applied Config

Write a starter template:

agentbox init

Export the effective config AgentBox would actually use:

agentbox init --export

Export the effective config after applying CLI overrides:

agentbox init --export \
  --image agentbox:php \
  --docker-network cherrylab \
  --allow api.anthropic.com,docs.php.net \
  --exclude .env \
  --mount ro:./docs:/opt/docs \
  --tool claude \
  --tool-config claude=~/.claude \
  --env APP_ENV=local

This is useful when you want to start from flags, inspect the final merged settings, then persist them into project config.

Inspect With Overrides

Preview the resolved config without writing it:

agentbox inspect
agentbox inspect --json
agentbox inspect --docker-network cherrylab --allow api.anthropic.com --exclude .env

Preview the resulting policy classification with the same override surface:

agentbox explain
agentbox explain --docker-socket=true
agentbox explain --allow api.anthropic.com --docker-network cherrylab

inspect, explain, init --export, shell, rebuild, and direct tool launches all accept the same config-style flags, so you can test a setup before persisting it.

Installation

Install the latest published release binary:

curl -fsSL https://raw.githubusercontent.com/monkeymonk/agentbox/main/install.sh | bash

This installer:

• downloads the release asset for the current platform
• verifies checksums.txt when checksum tools are available
• installs to /usr/local/bin on Linux and macOS by default
• installs to ~/bin by default when run from common Windows shells (mingw, msys, cygwin)
• optionally builds the base agentbox:latest image after installing the CLI

Supported release artifacts:

• Linux: amd64, arm64
• macOS: amd64, arm64
• Windows: amd64, arm64

Useful installer overrides:

AGENTBOX_VERSION=v0.2.1 curl -fsSL https://raw.githubusercontent.com/monkeymonk/agentbox/main/install.sh | bash
AGENTBOX_INSTALL_DIR="$HOME/.local/bin" curl -fsSL https://raw.githubusercontent.com/monkeymonk/agentbox/main/install.sh | bash
AGENTBOX_BUILD_IMAGE=false curl -fsSL https://raw.githubusercontent.com/monkeymonk/agentbox/main/install.sh | bash

From source:

git clone https://github.com/monkeymonk/agentbox.git
cd agentbox
make build
make image

Notes:

• make build builds the host agentbox CLI only.
• make install installs that host agentbox CLI into $(PREFIX)/bin.
• make image rebuilds the local agentbox:latest base image with --no-cache, so bundled tools installed in packaging/Dockerfile such as Claude Code and Codex are refreshed.
• After rebuilding the image, run agentbox rebuild in the target project to recreate its runtime container from the new image.

Source builds require Go 1.25+ and Docker.

Verify

agentbox
agentbox version
agentbox --version
agentbox -V
agentbox doctor
cd ~/work/my-project
agentbox claude

Development

make build
make test
make image
make clean

Typical local update flows:

• Host CLI only:

make install

• Bundled runtime tools or agentbox-launch changed:

make image
agentbox rebuild

License

MIT