█████╗  ██████╗ ███████╗███╗   ██╗████████╗██████╗  ██████╗ ██╗  ██╗
██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔══██╗██╔═══██╗╚██╗██╔╝
███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝██║   ██║ ╚███╔╝ 
██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗██║   ██║ ██╔██╗ 
██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██████╔╝╚██████╔╝██╔╝ ██╗
╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═════╝  ╚═════╝ ╚═╝  ╚═╝

agentbox

Run AI coding agents in isolated containers — one folder, one agent, zero host exposure.

Agentbox spins up an isolated container (Docker or Podman), installs your chosen AI coding agent inside it, and mounts a single host folder as the agent's only view of the filesystem. The agent cannot reach anything outside that folder or outside its allowed network endpoints. When the session ends, you review a diff and approve exactly what gets written back.

Three frontends, one engine: a scriptable CLI, a keyboard-driven TUI, and a desktop GUI.

---

Quick start

# 1. Build
cargo build --release -p agentbox-cli

# 2. Create a box config
cat > box.yaml << 'EOF'
agent: claude-code
folder:
  path: ./my-project
lifecycle: ephemeral
provider:
  name: anthropic
  type: anthropic
  model: claude-sonnet-4-6
  auth: ${env:ANTHROPIC_API_KEY}
EOF

# 3. Export your API key
export ANTHROPIC_API_KEY=sk-ant-...

# 4. Run
./target/release/agentbox up --config box.yaml

First run pulls the base image and installs the agent (~1–2 min). Subsequent runs reuse the cached image and start in seconds.

---

Features

• 4 agents — Claude Code, OpenCode, Pi, Codex (OpenAI)
• All provider types — Anthropic, OpenAI, any OpenAI-compatible endpoint (Ollama, llama.cpp, LiteLLM, OpenRouter)
• Egress allowlist — Drop-by-default iptables rules; only the provider API hostname gets through
• Two sync modes — mount (live bind-mount) or snapshot (copy-in → diff → review → copy-out)
• Persistent boxes — Named containers with state volumes survive across sessions
• Docker or Podman — auto-detected; pin with backend: docker / backend: podman in box.yaml
• OAuth support — In-container device-code flow; token cached in a named volume
• CLI / TUI / GUI — Same engine, pick your interface

---

Agents

ID	Name	Providers
claude-code	Claude Code	anthropic
opencode	OpenCode	anthropic, openai, openai-compatible
pi	Pi	anthropic, openai, openai-compatible (15+ via models.json)
codex	Codex	openai, openai-compatible

Add a custom agent by dropping a YAML manifest in manifests/. See docs/usage.md §9 for the schema.

---

Building

Prerequisites

Platform	Requirements
All	Docker Engine / Docker Desktop or Podman · Rust + Cargo
Linux (GUI only)	libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev

Docker:

docker info          # verify Docker is running

Podman (Linux — enable the Docker-compatible socket):

systemctl --user enable --now podman.socket
podman info          # verify Podman is running

To use Podman, add backend: podman to your box.yaml (or set DOCKER_HOST and use the default backend: auto):

backend: podman

CLI + TUI

cargo build --release
# Binaries: ./target/release/agentbox   ./target/release/agentbox-tui
cargo install --path cli    # optional: install to ~/.cargo/bin
cargo install --path tui

GUI (Tauri)

# Linux: sudo apt install libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1-dev
cd gui/src-tauri && cargo run
# or: cargo install tauri-cli && cargo tauri dev

---

Documentation

Full reference: docs/usage.md

Covers: all CLI commands, TUI navigation, GUI usage, box.yaml schema, auth reference syntax, egress allowlist, snapshot diff workflow, persistent boxes, OAuth, troubleshooting.

---

License

Licensed under the MIT License.