agentbox

Generate devcontainer setups for running Claude Code and Codex CLI in sandboxed environments with full permissions and network isolation.

Why

Claude Code and Codex CLI work best with full permissions -- file read/write, command execution, and network access. But granting those on your host machine is risky.

agentbox generates a devcontainer that gives Claude Code and Codex CLI full permissions inside a network-isolated Docker container. An iptables firewall with domain-level allowlisting ensures the coding tools can only reach explicitly approved domains, making "bypass permissions" mode safe to use.

Features

Auto-detection -- Scans for marker files (go.mod, package.json, Cargo.toml, etc.) at the project root and one level deep
Multi-stack support -- Go, Node/TypeScript, Python, Rust, and Ruby
Network isolation -- iptables default-DROP policy with ipset allowlist and dnsmasq for dynamic domains
Interactive wizard -- TUI for stack selection and domain configuration (powered by charmbracelet/huh)
Non-interactive mode -- --non-interactive / -y flag for CI pipelines and scripting
Settings sync -- Copies host Claude Code settings with jq deep-merge; copies Codex CLI config on first run
LSP plugin configuration -- Auto-configures Claude Code LSP plugins per detected stack
Runtime management via mise -- Installs language runtimes through mise

Installation

Homebrew

brew install bjro/tap/agentbox

GitHub Releases

Download a pre-built binary from the releases page.

From source

go install github.com/bjro/agentbox@latest

Note: Homebrew and GitHub Releases will be available with the first release. Building from source works today.

Quick Start

cd my-project
agentbox init          # interactive wizard
# or
agentbox init -y       # auto-detect stacks, no prompts

Example output:

Stacks: [go]
Generated .devcontainer/ with 11 files and .agentbox.yml

Then open the project in VS Code and select Dev Containers: Reopen in Container, or use DevPod to launch the container.

See Generated Files for details on what gets created.

CLI Reference

`agentbox init`

Generate a .devcontainer/ directory with all configuration files.

Flag	Short	Type	Default	Description
`--stack`		string slice	auto-detect	Comma-separated stack IDs (e.g., `--stack go,node`). Overrides auto-detection.
`--extra-domains`		string slice	none	Additional domains to allowlist beyond per-stack defaults (e.g., `--extra-domains api.example.com`)
`--dir`		string	current directory	Target project directory
`--non-interactive`	`-y`	bool	`false`	Skip all prompts, use detected stacks and defaults
`--runtime-version`		string slice	none	Runtime version overrides as `tool=version` pairs (e.g., `--runtime-version go=1.22,node=20`)

`agentbox update`

Regenerate agentbox-managed devcontainer files while preserving user customizations.

Flag	Type	Default	Description
`--stack`	string slice	from `.agentbox.yml`	Override stacks (persists to `.agentbox.yml`). Reuses recorded stacks if omitted.
`--extra-domains`	string slice	from `.agentbox.yml`	Override extra domains (persists to `.agentbox.yml`)
`--dir`	string	current directory	Target project directory
`--force`	bool	`false`	Force full regeneration even if the Dockerfile custom stage is missing

`agentbox --version`

Print the version string and exit.

Supported Stacks

Stack	Name	Runtime	LSP	Detection Triggers
`go`	Go	go@latest	gopls	`go.mod`
`node`	Node/TypeScript	node@lts	typescript-language-server	`package.json`, `tsconfig.json`
`python`	Python	python@latest	pyright	`requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile`
`rust`	Rust	rust@latest	rust-analyzer	`Cargo.toml`
`ruby`	Ruby	ruby@latest	solargraph	`Gemfile`, `.gemspec`

* *.gemspec is detected via glob pattern in the detection engine, not as an exact filename in the stack registry.

Node/npm is always included in the generated container regardless of detected stacks, because Claude Code requires it.

Detection scans the project root and one level deep, skipping vendor/, node_modules/, .git/, testdata/, and .devcontainer/.

How It Works

agentbox generates a self-contained devcontainer with three main components: a Dockerfile, a firewall, and a settings sync mechanism.

Dockerfile

The generated Dockerfile uses debian:bookworm-slim as the base image and installs:

mise for language runtime management (Go, Node, Python, Rust, Ruby)
LSP servers per detected stack (gopls, pyright, typescript-language-server, etc.)
Claude Code and Codex CLI via npm install -g @anthropic-ai/claude-code @openai/codex
Sandbox runtime: bubblewrap (required by Codex CLI sandbox mode)
Firewall tooling: iptables, ipset, dnsmasq
Developer experience: zsh, git-delta, GitHub CLI, fzf

Firewall

The firewall uses a three-layer architecture to enforce domain-level network isolation:

                        Container Startup
                              |
                    postStartCommand runs
                              |
                      chown volumes
                              |
                  sync-claude-settings.sh
                              |
                  sync-codex-settings.sh
                              |
                      init-firewall.sh
                              |
          +-----------------------+-----------------------+
          |                       |                       |
Resolve static domains    Configure dnsmasq        Set iptables
into ipset hash:ip        for dynamic domains      OUTPUT -> DROP
          |                       |                       |
(dig once, cache IPs)     (re-resolve on TTL)     (allow ipset only)
          |                       |                       |
          +-----------------------+-----------------------+
                                  |
                   Claude Code and Codex CLI ready
                    (network limited to allowlist)

Static domains (e.g., sentry.io, registry.npmjs.org) have stable IPs. They are resolved once at startup and cached in an ipset.

Dynamic domains (e.g., *.anthropic.com, proxy.golang.org) use CDNs or rotating IPs. They are managed by dnsmasq, which re-resolves them on TTL expiry and updates the ipset automatically.

The always-on allowlist includes domains required for Claude Code and Codex CLI to function regardless of stack:

Domain	Category	Purpose
`github.com`	dynamic	GitHub web and git-over-HTTPS
`api.github.com`	dynamic	GitHub REST API
`*.anthropic.com`	dynamic	Anthropic API for Claude Code
`api.openai.com`	dynamic	OpenAI API for Codex CLI
`auth.openai.com`	dynamic	OpenAI auth for Codex ChatGPT login flow
`auth0.openai.com`	dynamic	OpenAI auth0 for Codex ChatGPT token refresh
`chatgpt.com`	dynamic	ChatGPT for Codex ChatGPT login auth flow
`accounts.openai.com`	dynamic	OpenAI accounts for Codex ChatGPT auth
`sentry.io`	static	Error reporting for Claude Code
`statsig.com`	static	Feature flags and experimentation for Claude Code

Each detected stack adds its own domains (package registries, module proxies, etc.).

Settings Sync

sync-claude-settings.sh copies the generated claude-user-settings.json into ~/.claude/settings.json inside the container. On first run it creates the file; on subsequent runs it uses jq to deep-merge new settings with existing ones, preserving any manual changes.

sync-codex-settings.sh copies the generated codex-config.toml into ~/.codex/config.toml inside the container. On first run it creates the file; on subsequent runs it skips the copy to preserve any manual changes (copy-on-first-run strategy, unlike the Claude Code deep-merge approach).

devcontainer.json

The generated devcontainer.json configures:

containerEnv forwards OPENAI_API_KEY from the host for Codex CLI authentication
Mounts for bash history, Claude config, Codex config, GitHub CLI config, and gitconfig
postStartCommand that chains settings sync (Claude Code and Codex CLI) and firewall initialization
Capabilities: NET_ADMIN and NET_RAW (required for iptables/ipset)
Security: seccomp=unconfined (required for iptables inside the container)
Extensions: Claude Code (anthropic.claude-code) and Codex (openai.chatgpt) VS Code extensions are auto-configured

Generated Files

Running agentbox init creates a .devcontainer/ directory and a .agentbox.yml config file.

`.devcontainer/`

File	Description
`Dockerfile`	Container image with runtimes, LSPs, Claude Code, Codex CLI, and firewall tooling
`devcontainer.json`	VS Code / DevPod configuration with mounts, capabilities, and startup commands
`init-firewall.sh`	Network isolation setup script (runs as root via `sudo`)
`warmup-dns.sh`	Pre-resolves dynamic domains through dnsmasq after firewall init
`dynamic-domains.conf`	Editable list of dynamic domains for dnsmasq
`claude-user-settings.json`	Claude Code settings with bypass permissions mode and LSP plugins
`sync-claude-settings.sh`	Copies/merges Claude Code settings into the container
`codex-config.toml`	Codex CLI settings with full-auto approval policy and sandbox mode
`sync-codex-settings.sh`	Copies Codex CLI settings into the container (first-run only)
`mise-config.toml`	Runtime version configuration for mise (Go, Node, etc.)
`README.md`	Per-project documentation for the generated devcontainer

`.agentbox.yml`

Created in the project root. Records the stacks, extra domains, generation timestamp, and agentbox version used. This file enables future agentbox commands to understand the current configuration.

FAQ

How do I change runtime versions?

Edit .devcontainer/mise-config.toml:

[tools]
go = "1.22"
node = "20"

Then rebuild the container. This file is preserved across agentbox update runs -- it is never overwritten.

During initial setup, you can also use the --runtime-version flag:

agentbox init --runtime-version go=1.22,node=20

How do I add my own tools?

Add RUN commands in the custom stage at the bottom of .devcontainer/Dockerfile:

FROM agentbox AS custom

RUN go install github.com/user/tool@latest && mise reshim
RUN pip install my-tool && mise reshim
RUN npm install -g some-cli

The custom stage is preserved when you run agentbox update. The agentbox stage above it is regenerated. Add && mise reshim after go install or pip install so the binaries are discoverable on PATH.

How do I allow additional domains through the firewall?

Use the --extra-domains flag on init or update:

agentbox init -y --extra-domains api.example.com,cdn.example.com
agentbox update --extra-domains api.example.com

The -y flag is required on init because in interactive mode the wizard prompts for extra domains and overrides the --extra-domains flag. In non-interactive mode (-y), the flag is applied directly.

Extra domains are saved in .agentbox.yml and reused on subsequent agentbox update runs (unless overridden with --extra-domains). All user-specified domains are classified as dynamic and managed by dnsmasq with automatic re-resolution.

How do I pass API keys into the container?

Add entries to containerEnv in .devcontainer/devcontainer.json:

"containerEnv": {
  "OPENAI_API_KEY": "${localEnv:OPENAI_API_KEY}",
  "ANTHROPIC_API_KEY": "${localEnv:ANTHROPIC_API_KEY}"
}

The ${localEnv:VAR} syntax forwards the variable from your host. Note that devcontainer.json is regenerated by agentbox update, so you will need to re-add custom entries after updating. To make this easier, version-control the file and use git diff to identify and restore your custom entries after an update.

How do I update after changing stacks?

agentbox update --stack go,node

This regenerates the agentbox-managed portion of .devcontainer/ for the new stack combination while preserving your custom stage in the Dockerfile and mise-config.toml. The new stacks are saved to .agentbox.yml. Without --stack, the update reuses whatever stacks are recorded in .agentbox.yml.

What's safe to edit vs. what gets overwritten?

File	On `agentbox update`
`Dockerfile` (custom stage)	Preserved -- your `FROM agentbox AS custom` block is kept intact
`mise-config.toml`	Preserved -- your version pins are never overwritten
`Dockerfile` (agentbox stage)	Regenerated
`devcontainer.json`	Regenerated
`init-firewall.sh`, `warmup-dns.sh`	Regenerated
`sync-claude-settings.sh`, `sync-codex-settings.sh`	Regenerated
`claude-user-settings.json`, `codex-config.toml`	Regenerated
`dynamic-domains.conf`	Regenerated
`.devcontainer/README.md`	Regenerated
`.agentbox.yml`	Updated (stacks, domains, timestamp)

How do I add extra VS Code extensions?

Add extension IDs to the customizations.vscode.extensions array in .devcontainer/devcontainer.json:

"customizations": {
  "vscode": {
    "extensions": [
      "anthropic.claude-code",
      "openai.chatgpt",
      "esbenp.prettier-vscode",
      "dbaeumer.vscode-eslint"
    ]
  }
}

Note that devcontainer.json is regenerated by agentbox update, so custom extensions will need to be re-added after updating. To make this easier, version-control the file and use git diff to identify and restore your custom entries after an update.

Contributing

Prerequisites

Go 1.25+
golangci-lint v2

Build and Test

go build ./...                          # Build
go test ./...                           # Unit tests
go test -tags integration ./...         # Unit + integration tests
golangci-lint run ./...                 # Lint

Project Structure

cmd/                  CLI commands (Cobra)
internal/
  stack/              Stack metadata registry
  detect/             Stack auto-detection
  render/             Template rendering engine
  firewall/           Domain allowlist logic
  config/             .agentbox.yml handling
  wizard/             Interactive TUI wizard

Architecture Decisions

Significant design choices are documented as Architecture Decision Records in decisions/.

License

MIT. See LICENSE for the full text.

Name		Name	Last commit message	Last commit date
.beans		.beans
.devcontainer		.devcontainer
.github/workflows		.github/workflows
cmd		cmd
decisions		decisions
internal		internal
.agentbox.yml		.agentbox.yml
.beans.yml		.beans.yml
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Latest commit

History

Folders and files

Repository files navigation