Agentbox - Coding Agent Sandbox

There's no perfect way to sandbox agents (yet), but at least we can try limiting the damage using containers.

Agentbox is a simple Docker-based coding agent sandbox, originally inspired by running Batrachian Toad as a general-purpose coding assistant TUI and now generalized to more tools.

Whatever agent you prefer, Agentbox aims to provide a reliable and isolated environment which will help you boostrap pretty much any development environment.

Motivation

I found myself wanting to quickly spin up isolated coding environments for AI agents, without having to deal with complex orchestration tools or heavy VMs, and also wanting to limit CPU usage from Batrachian Toad itself.

Features

The default container provides a Debian userland, Homebrew, (optional) Docker-in-Docker, and ssh/mosh server to run these:

• Batrachian Toad: A unified interface for AI in your terminal
• Copilot CLI: My usual go-to
• OpenCode: Another coding assistant pre-installed
• Development Environment: Debian Bookworm with essential development tools
• Package Managers: Homebrew and APT package management, plus uv, bun, etc.
• Docker-in-Docker: Docker support for containerized workflows (requires you to run the container in privileged mode, so be careful)
• Service Control: Fine-grained control over which services start using environment variables (ENABLE_DOCKER, ENABLE_SSH, ENABLE_RDP)
• Remote Access: SSH (port 22) connectivity (disabled by default)
• Persistent Storage: optional data and agent home directory persistence
• Agent SKILLs and CI Scaffolding: The agent user ships with a repository skeleton/scaffolding for common development steps, as well as agent skils to go with it (see the Makefile inside /home/agent)

Roadmap

• CPU and memory limits (basic Docker resource constraints)
• Network isolation options
• Other sandboxing techniques (gVisor, Kata Containers, etc.)

Service Configuration

Agentbox uses environment variables to control which services start at container launch:

• ENABLE_DOCKER=true - Start Docker daemon (for Docker-in-Docker support)
• ENABLE_SSH=true - Start SSH server (port 22)
• ENABLE_RDP=true - Start RDP server (port 3389)
• AGENTBOX_ENVIRONMENT=cli|gui - Image-provided environment marker (cli for headless/CLI, gui for desktop images)

Default behavior: All services are disabled unless explicitly enabled.

Examples:

# Default - all services disabled
docker run -d agentbox

# Enable only Docker daemon
docker run -d -e ENABLE_DOCKER=true agentbox

# Enable Docker and SSH for development
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -p 22:22 agentbox

# Full desktop experience with all services (GUI image)
docker run -d -e ENABLE_DOCKER=true -e ENABLE_SSH=true -e ENABLE_RDP=true -p 22:22 -p 3389:3389 agentbox:gui

Quick Start

Optional Tool Installs

Run make -C ~ tools (or make -C ~ node, make -C ~ go, make -C ~ gemini, make -C ~ vibe) to install optional tooling via Homebrew/uv.

Workspace skeleton

Agentbox ships a built-in project skeleton at /home/agent/workspace-skel.

To copy it into your current /workspace without overwriting existing files:

make init-workspace

See docs/workspace-skeleton.md for details.

GUI Image

The GUI build is published as the :gui tag (also <release>-gui) and includes XFCE, XRDP, and VS Code.

Docker Compose

The docker compose file includes an example of a set of agent workspaces that you can customize. Use the Makefile to quickly start/stop the instances and enter one of them by typing:

make enter-<instance-name>

That will start (or resume) a tmux session inside the container, where you can run your agents.

Using Agentbox Manager (still WIP)

The Agentbox Manager is a first stab at a TUI for easily managing multiple agentbox instances with automatic naming, folder picker, and proper permission handling.

1. Clone or download this repository
2. Run the quick start script:

Manager Features:

• 📁 Folder Picker: Browse and select workspace directories easily
• 🏷️ Automatic Naming: Container names and hostnames based on folder names
• 👤 PUID/PGID Support: Automatic permission alignment with host system
• 🐳 Docker Compose: Leverages docker-compose for orphan cleanup and resource management
• 🔄 Multi-Instance: Manage multiple development environments simultaneously

Manager Usage:

• Use arrow keys to navigate instances
• Press c to create a new instance
• Press enter to connect to selected instance
• Press s to start/stop instances
• Press q to quit

Using Docker Compose (Manual)

If you prefer to use docker-compose directly:

1. Clone or download this repository
2. Create a docker-compose.override.yml file to enable services:

version: "3.8"
services:
  agentbox:
    environment:
      - ENABLE_DOCKER=true
      - ENABLE_SSH=true
      - ENABLE_RDP=true
    ports:
      - "22:22"
      - "3389:3389"

3. Run the container:

docker-compose up -d

3. Connect to the container:

Via RDP (Graphical Desktop):

• RDP Client: localhost:3389
• Username: agent
• Password: smith

Via SSH (Terminal):

ssh agent@localhost -p 22
# Password: smith

Using Docker Directly

# Build the headless image
docker build -t agentbox .

# Build the GUI image
docker build -t agentbox:gui --target gui .

# Run the container with selected services (GUI image)
docker run -d \
  --name agentbox \
  --privileged \
  -e ENABLE_DOCKER=true \
  -e ENABLE_SSH=true \
  -e ENABLE_RDP=true \
  -p 22:22 \
  -p 3389:3389 \
  -v $(pwd):/workspace \
  agentbox:gui

Using Batrachian Toad

Once connected to the container:

1. Start Toad:

toad

2. Or start with a specific project directory:

toad /workspace

3. Or launch directly with an agent:

toad -a open-hands

Security Notes

• Service Control: By default, all services (Docker, SSH, RDP) are disabled. Explicitly enable only what you need using environment variables.
• Default passwords are weak - change them for production use
• The container needs to run in privileged mode for Docker-in-Docker to be available to your agents (it's better than nothing)
• Consider using SSH keys instead of password authentication
• For production use, consider disabling unnecessary services and changing default credentials

Credits

This project is loosely based on my ancient rcarmo/docker-templates/desktop-chrome with an updated userland.

License

MIT