Toadbox - Coding Agent Sandbox

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

Toadbox is a simple Docker-based coding agent sandbox featuring Batrachian Toad as a general-purpose coding assistant TUI, which will help you boostrap pretty much any current AI agent.

The container provides a Debian userland, Homebrew, (optional) Docker-in-Docker, ssh/mosh server, and a minimal VNC desktop 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

• Batrachian Toad: A unified interface for AI in your terminal
• Development Environment: Debian Bookworm with essential development tools
• Package Managers: Homebrew and APT package management
• Docker-in-Docker: Docker support for containerized workflows (requires you to run the container in privileged mode, so be careful)
• Remote Access: SSH (port 2222) and VNC (port 5901) connectivity
• Minimal Desktop: Openbox window manager with minimal utilities, so you can run graphical applications, Playwright, etc.
• Persistent Storage: optional data and user home directory persistence

Roadmap

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

Quick Start

Using Toadbox Manager (still WIP)

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

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

./start-manager.sh

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. Run the container:

docker-compose up -d

1. Connect to the container:

Via VNC (Graphical Desktop):

• VNC Viewer: localhost:5901
• Password: changeme

Via SSH (Terminal):

ssh user@localhost -p 2222
# Password: changeme

Using Docker Directly

# Build the image
docker build -t toadbox .

# Run the container
docker run -d \
--name toadbox \
--privileged \
-p 2222:22 \
-p 5901:5901 \
-v $(pwd):/workspace \
toadbox

Using Batrachian Toad

Once connected to the container:

1. Start Toad:

toad

1. Or start with a specific project directory:

toad /workspace

1. Or launch directly with an agent:

toad -a open-hands

Security Notes

• 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 extra (in)security, consider running the manager with a remote Docker socket to a VM where the actual containers run.

Credits

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

License

MIT