exitbox

README

  _____      _ _   ____
 | ____|_  _(_) |_| __ )  _____  __
 |  _| \ \/ / | __|  _ \ / _ \ \/ /
 | |___ >  <| | |_| |_) | (_) >  <
 |_____/_/\_\_|\__|____/ \___/_/\_\
              By Cloud Exit / https://cloud-exit.com

ExitBox

Multi-Agent Container Sandbox by Cloud Exit

Run AI coding assistants (Claude, Codex, OpenCode) in isolated containers with defense-in-depth security.

Getting Started

Install ExitBox and run the interactive setup wizard to configure your environment:

# Install (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/cloud-exit/exitbox/main/scripts/install.sh | sh

# Run the setup wizard
exitbox setup

The setup wizard guides you through:

1. Developer role — Frontend, Backend, Fullstack, DevOps, Data Science, Mobile, Embedded, or Security
2. Languages — Pre-selected based on your role, customize as needed
3. Tool categories — Build tools, databases, networking, DevOps, security, and more
4. Agents — Choose which AI assistants to enable (Claude, Codex, OpenCode)

The wizard generates a tailored config.yaml with your preferences. You can re-run it at any time with exitbox setup.

Features

Security

The project's security posture is rated High / Robust, employing a "Defense in Depth" strategy:

1. DNS Isolation (The "Moat"): Containers cannot resolve external domain names directly. This forces all traffic through the proxy, as the container "knows" nothing of the outside internet.
2. Mandatory Proxy Usage: Since direct DNS fails, tools are forced to use the configured http_proxy. Bypassing these variables results in immediate connection failure.
3. Proxy Access Control: The Squid proxy actively inspects destinations, enforcing a strict allow/deny policy (returning 403 Forbidden for blocked domains).
4. Capability Restrictions: CAP_NET_RAW and other capabilities are dropped, preventing raw socket creation and network enumeration attacks (e.g., ping is disabled).

Core Features:

• Rootless Containers: Runs without host root privileges using Podman's user namespaces
• Alpine Base Image: Minimal Alpine Linux base (~5 MB) with a managed tool list
• Supply-Chain Hardened Installs: Claude Code is installed via direct binary download with SHA-256 checksum verification against Anthropic's signed manifest — no curl | bash
• Squid Proxy Firewall: Proxy-based destination filtering with explicit allowlist rules
• Hard Egress Isolation: Agent containers run on an internal-only network and can exit only via Squid
• No Privilege Escalation: --security-opt=no-new-privileges:true enforced
• Capability Dropping: --cap-drop=ALL removes all Linux capabilities
• Resource Limits: Default 8GB RAM / 4 CPUs to prevent DoS
• Secure Defaults: No automatic mounting of sensitive SSH keys or AWS credentials

Sandbox-Aware Agents

ExitBox automatically injects sandbox instructions into each agent on container start. This tells the agent it is running inside a restricted container so it won't attempt actions that can't work (e.g., running docker, podman, or managing infrastructure).

Instructions are written to each agent's native global instructions file:

Agent	Instructions file
Claude	~/.claude/CLAUDE.md
Codex	~/.codex/AGENTS.md
OpenCode	~/.config/opencode/AGENTS.md

If the file already exists (e.g., from your own global instructions), ExitBox appends the sandbox notice once. The instructions inform the agent about network restrictions, dropped capabilities, and the read-only nature of the environment so it can focus on writing and debugging code within /workspace.

Containers

• Podman-First: Optimized for Podman (rootless, daemonless) with Docker fallback
• Multi-Agent Support: Run Claude Code, OpenAI Codex, or OpenCode
• Project Isolation: Each project gets its own containerized environment
• Development Profiles: Pre-configured environments for Rust, Python, Go, Node.js, and more
• Custom Tools: Add Alpine packages to any image via -t flag or config.yaml

Usability

• Cross-Platform: Native binaries for Linux, macOS, and Windows
• Setup Wizard: Interactive TUI that configures your environment based on your developer role
• YAML Config: Clean, readable configuration with config.yaml and allowlist.yaml
• Config Import: All platforms use managed config (import-only). Use exitbox import <agent> to seed host config.
• Simple Commands: Just run exitbox claude to get started
• CLI Shorthands: All flags have single-letter aliases (-f, -r, -t, -a, etc.)
• Session Allow-URLs: Temporarily allow extra domains with -a — no config file edits, no restarts

Supported Agents

Agent	Description	Host Requirement
claude	Anthropic's Claude Code CLI	None (installed in container)
codex	OpenAI's Codex CLI	None (downloaded)
opencode	OpenCode AI assistant	None (binary download)

All agents are installed inside the container. Existing host config (~/.claude, etc.) is imported once into managed storage on first run. Use exitbox import <agent> (or exitbox import all) to re-seed from host config.

Installation

Prerequisites

• Podman (recommended) or Docker — at least one is required; Podman is preferred for its rootless, daemonless design
• For Windows: Docker Desktop provides the Docker CLI that ExitBox uses

Quick Install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/cloud-exit/exitbox/main/scripts/install.sh | sh

This downloads the latest release binary, verifies its SHA-256 checksum, and installs to ~/.local/bin/.

Linux

# Install Podman (recommended) or Docker
sudo apt update && sudo apt install -y podman   # Ubuntu/Debian
# OR: install Docker - see https://docs.docker.com/engine/install/

# Install exitbox
curl -fsSL https://raw.githubusercontent.com/cloud-exit/exitbox/main/scripts/install.sh | sh

# Run the setup wizard
exitbox setup

# Run an agent
exitbox claude

macOS

# Install Podman (recommended) or Docker
brew install podman
podman machine init && podman machine start
# OR: brew install --cask docker

# Install exitbox
curl -fsSL https://raw.githubusercontent.com/cloud-exit/exitbox/main/scripts/install.sh | sh

# Run the setup wizard
exitbox setup

Windows

ExitBox runs natively on Windows with Docker Desktop.

1. Install Docker Desktop for Windows
2. Download the latest exitbox-windows-amd64.exe from Releases
3. Rename to exitbox.exe and place in a directory on your PATH (e.g., C:\Users\<you>\AppData\Local\bin\)
4. Run the setup wizard:

exitbox setup

Windows (WSL2)

Alternatively, use ExitBox inside WSL2 for a Linux-native experience:

# In PowerShell as Administrator
wsl --install -d Ubuntu

Then in WSL2:

sudo apt update && sudo apt install -y podman
curl -fsSL https://raw.githubusercontent.com/cloud-exit/exitbox/main/scripts/install.sh | sh
exitbox setup

Build from Source

git clone https://github.com/Cloud-Exit/exitbox.git
cd exitbox
make build       # builds ./exitbox
make install     # installs to ~/.local/bin/exitbox

Quick Start

# Run the setup wizard (first time)
exitbox setup

# Navigate to your project
cd /path/to/your/project

# Run an agent (builds image automatically on first run)
exitbox claude

# Or run other agents
exitbox codex
exitbox opencode

ExitBox automatically:

• Builds the container image if needed
• Imports your existing config (~/.claude, ~/.codex, etc.) on first run
• Mounts your project directory
• Sets up the network firewall (Squid proxy)

Commands

Setup

exitbox setup             # Run the interactive setup wizard (recommended first step)

Running Agents

exitbox claude [args]     # Run Claude Code
exitbox codex [args]      # Run Codex
exitbox opencode [args]   # Run OpenCode

Management

exitbox list              # List available agents and build status
exitbox enable <agent>    # Enable an agent
exitbox disable <agent>   # Disable an agent
exitbox rebuild <agent>   # Force rebuild of agent image
exitbox rebuild all       # Rebuild all enabled agents
exitbox uninstall <agent> # Remove agent images and config
exitbox aliases           # Print shell aliases for ~/.bashrc
exitbox info              # Show system information

Profile Management

exitbox <agent> profile list       # List available profiles
exitbox <agent> profile add <name> # Add a development profile
exitbox <agent> profile remove <n> # Remove a profile
exitbox <agent> profile status     # Show current profiles

Utilities

exitbox info              # Show system information
exitbox logs <agent>      # Show latest agent log file
exitbox clean             # Clean unused container resources
exitbox clean all         # Remove all exitbox images
exitbox projects          # List known projects

Options

exitbox -f claude              # Disable network firewall *DANGEROUS*
exitbox -r claude              # Mount workspace as read-only (safety)
exitbox -v claude              # Enable verbose output
exitbox -n claude              # Don't pass host environment variables
exitbox -n -e MY_KEY=val claude  # Only pass specific env vars
exitbox -i /tmp/foo claude     # Mount /tmp/foo into /workspace/foo
exitbox -t nodejs,go claude    # Add Alpine packages to image (persisted)
exitbox -a api.example.com claude  # Allow extra domains for this session
exitbox -u claude              # Check for and apply agent updates

All flags have long forms: -f/--no-firewall, -r/--read-only, -v/--verbose, -n/--no-env, -i/--include-dir, -t/--tools, -a/--allow-urls, -u/--update.

Available Profiles

Profiles are pre-configured development environments. The setup wizard suggests profiles based on your developer role, or you can add them manually.

Profile	Description
base	Base development tools
build-tools	Build toolchain helpers
shell	Shell and file transfer utilities
networking	Network diagnostics and tooling
c	C/C++ toolchain (gcc, make, cmake)
node	Node.js runtime with npm and JS tooling
python	Python 3 with pip
rust	Rust toolchain with cargo
go	Go runtime (arch-aware, checksum verified)
java	OpenJDK with Maven and Gradle
ruby	Ruby with bundler
php	PHP with composer
database	Database CLI clients
devops	Docker CLI / kubectl / helm / opentofu / kind
web	Web server/testing tools
security	Security diagnostics tools
flutter	Flutter SDK

Configuration

ExitBox uses YAML configuration files stored in ~/.config/exitbox/ (Linux/macOS) or %APPDATA%\exitbox\ (Windows).

Setup Wizard

The recommended way to configure ExitBox is through the setup wizard:

exitbox setup

The wizard generates config.yaml and allowlist.yaml tailored to your developer role. It runs automatically on first use, or you can re-run it to reconfigure at any time.

config.yaml

The main configuration file controls which agents are enabled, extra packages, and default settings:

version: 1
roles:
  - backend
  - devops

agents:
  claude:
    enabled: true
  codex:
    enabled: false
  opencode:
    enabled: true

tools:
  user:
    - postgresql-client
    - redis

settings:
  auto_update: false
  status_bar: true            # Show "ExitBox <version> - <agent>" bar at top of terminal
  default_flags:
    no_firewall: false
    read_only: false
    no_env: false

The status_bar setting controls the thin status bar displayed at the top of the terminal while an agent is running. It is enabled by default. Set to false to disable it.

allowlist.yaml

The network allowlist is organized by category for readability:

version: 1
ai_providers:
  - anthropic.com
  - claude.ai
  - openai.com
  # ...

development:
  - github.com
  - npmjs.org
  - pypi.org
  # ...

cloud_services:
  - googleapis.com
  - amazonaws.com
  - azure.com

custom:
  - mycompany.com

Custom Tools

Add extra Alpine packages to your container images:

1. CLI flag (persisted automatically):

   exitbox -t nodejs,python3-dev claude
   

2. config.yaml:

   tools:
     user:
       - nodejs
       - python3-dev
   

The image rebuilds automatically when tools change.

Resource Limits

ExitBox enforces default resource limits to prevent runaway agents:

• Memory: 8GB
• CPU: 4 vCPUs

What Gets Mounted

ExitBox uses managed config (import-only). On first run, host config is copied into ~/.config/exitbox/<agent>/ and all mounts come from there. Host originals are never modified. Use exitbox import <agent> to re-seed from host config at any time.

Agent	Managed Path	Container Path
Claude	~/.config/exitbox/claude/.claude	/home/user/.claude
Claude	~/.config/exitbox/claude/.claude.json	/home/user/.claude.json
Claude	~/.config/exitbox/claude/.config	/home/user/.config
Codex	~/.config/exitbox/codex/.codex	/home/user/.codex
Codex	~/.config/exitbox/codex/.config/codex	/home/user/.config/codex
OpenCode	~/.config/exitbox/opencode/.opencode	/home/user/.opencode
OpenCode	~/.config/exitbox/opencode/.config/opencode	/home/user/.config/opencode
OpenCode	~/.config/exitbox/opencode/.local/share/opencode	/home/user/.local/share/opencode
OpenCode	~/.config/exitbox/opencode/.local/state	/home/user/.local/state
OpenCode	~/.config/exitbox/opencode/.cache/opencode	/home/user/.cache/opencode

Your project directory is mounted at /workspace.

When Codex is enabled, ExitBox publishes callback port 1455 on the shared exitbox-squid container and relays it to the active Codex container, so OrbStack/private-networking callback flows work reliably.

Note: SSH keys (~/.ssh) and AWS credentials (~/.aws) are NOT mounted by default for security.

Environment Variables

Variable	Description
VERBOSE	Enable verbose output
CONTAINER_RUNTIME	Force runtime (podman or docker)
EXITBOX_NO_FIREWALL	Disable firewall (true)
EXITBOX_SQUID_DNS	Squid DNS servers (comma/space list, default: 1.1.1.1,8.8.8.8)
EXITBOX_SQUID_DNS_SEARCH	Squid DNS search domains (default: . to disable inherited search suffixes)

Architecture

Alpine Base Image

All agent images are built on Alpine Linux. The base package list is embedded in the binary and shared by all image builds.

Alpine was chosen for:

• Small image size: ~5 MB base vs ~80 MB for Debian slim
• musl libc: Matches the native binaries shipped by Claude Code, git-delta, and yq
• Consistent package manager: apk is used everywhere — base image, profiles, and user tools

3-Layer Image Hierarchy

base image (Alpine + tools)
  └── core image (agent-specific install)
        └── project image (development profiles layered on)

Each layer uses label-based caching (exitbox.version, exitbox.agent.version, exitbox.tools.hash, exitbox.profiles.hash) so rebuilds are fast and incremental.

Supply-Chain Hardened Agent Installs

Claude Code is installed via direct binary download with SHA-256 checksum verification against Anthropic's signed manifest — no curl | bash. The download URL is auto-discovered from the official installer if the hardcoded endpoint ever changes. The build aborts on any checksum mismatch.

Network Firewall

ExitBox uses a Squid Proxy container to enforce strict destination allowlisting:

1. Hard egress control: Agent containers run on an internal-only network with no direct internet route.
2. Proxy path: Squid is dual-homed (internal + egress networks), so outbound traffic must traverse Squid.
3. Allowlist: Only destinations listed in allowlist.yaml are permitted through the proxy.
4. Fail closed: Missing or empty allowlist blocks all outbound destinations.

Configuring the Allowlist

Edit ~/.config/exitbox/allowlist.yaml and add domains to the custom list:

custom:
  - mycompany.com
  - api.internal.example.com

Domain formats:

• example.com allows example.com and its subdomains
• api.example.com allows only that host scope (and deeper subdomains)
• *.example.com is accepted as wildcard syntax
• 8.8.8.8 allows a specific IPv4 destination
• 2606:4700:4700::1111 allows a specific IPv6 destination

Temporary Domain Access

Allow extra domains for a single session without editing the allowlist:

exitbox -a api.example.com,cdn.example.com claude

The domains are merged into the Squid config and applied via hot-reload (squid -k reconfigure) — no proxy restart, no container restart, no connection drop. These domains do not persist across sessions.

Disabling the Firewall

exitbox --no-firewall claude   # *DANGEROUS* - disables all network restrictions

Why Podman?

Feature	Podman	Docker
Rootless by default	Yes	No (requires group)
Daemonless	Yes	No (requires daemon)
Security	Better isolation	Requires daemon root

On Windows, Docker Desktop is the primary supported runtime.

Troubleshooting

Podman: "cannot find UID/GID for user"

sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
podman system migrate

Podman on macOS: "Cannot connect to Podman"

podman machine start

Docker: Permission Denied

sudo usermod -aG docker $USER
newgrp docker

Windows: Docker Desktop not detected

Ensure Docker Desktop is running and the docker CLI is on your PATH. You can verify with:

docker info

Re-running the Setup Wizard

If your needs change or you want to reconfigure:

exitbox setup

Uninstallation

# Remove the binary
rm -f ~/.local/bin/exitbox

# Remove configuration and data
rm -rf ~/.config/exitbox ~/.cache/exitbox ~/.local/share/exitbox

# Remove container images
podman images | grep exitbox | awk '{print $3}' | xargs podman rmi -f
# OR for Docker:
docker images | grep exitbox | awk '{print $3}' | xargs docker rmi -f

On Windows, delete exitbox.exe and remove %APPDATA%\exitbox\.

License

AGPL-3.0 - see LICENSE file.

ExitBox is open-source software licensed under the GNU Affero General Public License v3.0. Commercial licensing is available from Cloud Exit for organizations that require proprietary usage terms.

Contributing

Contributions welcome via pull requests and issues.