ace-sandbox

A Manus-like agent sandbox powered by Claude Code. Runs Claude inside Docker containers with skills, project context, quality standards, and Cloudflare tunnels for sharing.

Quick Start

# 1. Build the container
docker build -t ace-sandbox:latest .

# 2. Login to Claude (one-time)
claude auth login

# 3. Copy .env.example to .env and add your keys
cp .env.example .env

# 4. Run a task
./run-sandbox.sh --skill web-builder "Build a portfolio website for a photographer"

Features

• undefinedSkills — domain-specific knowledge injected into Claude (web-builder, coder, researcher)
• undefinedProject context — pre-loaded requirements so Claude cannot miss them
• undefinedQuality standards — SANDBOX_CLAUDE.md enforces planning, verification, no placeholders
• undefinedNano Banana — AI image generation via Gemini (needs GEMINI_API_KEY)
• undefinedCloudflare tunnels — share your build instantly via expose-port.sh
• undefinedPortable — works with Claude Max subscription or API key

Usage

# Basic task
./run-sandbox.sh "Write a Python script that analyzes CSV files"

# With skill
./run-sandbox.sh --skill web-builder "Build an e-commerce site for a bakery"

# With project context
./run-sandbox.sh --skill web-builder --project my-client "Build the site per requirements"

# More turns for complex tasks
./run-sandbox.sh --max-turns 50 --skill web-builder "Build a full SaaS dashboard"

Adding Skills

Create a markdown file in skills/:

# Skill: My Skill Name

## Domain
What this skill covers.

## Checklist
- [ ] Item 1
- [ ] Item 2

Adding Project Context

Create a markdown file in projects/:

# Project: Client Name

## Requirements
- Exact pricing, services, contact info
- Design preferences
- Specific features needed

Advanced (MCP Memory)

If you have an MCP memory server running, use run-sandbox-advanced.sh which pre-fetches project context from the database.

Sharing Your Build

Inside the container, run:

expose-port.sh 3000

This starts a Cloudflare Quick Tunnel — gives you a public URL, auto-kills after 24h, no ports opened on your machine.

Platform Setup

macOS / Linux

# Prerequisites: Docker, Node.js 18+
npm install -g @anthropic-ai/claude-code
claude auth login
git clone https://github.com/cdwaage/ace-sandbox.git
cd ace-sandbox
docker build -t ace-sandbox:latest .
cp .env.example .env    # add GEMINI_API_KEY if you want AI image generation
./run-sandbox.sh --skill web-builder "Build a portfolio website"

Windows

Windows requires WSL2 (Windows Subsystem for Linux). Do NOT use PowerShell or CMD directly.

# Step 1: Install WSL2 (run in PowerShell as Administrator, one-time)
wsl --install
# Restart your computer after this completes

# Step 2: Open WSL terminal (Ubuntu) and install dependencies
sudo apt update && sudo apt install -y docker.io nodejs npm git
sudo usermod -aG docker $USER
# Log out and back in for docker group to take effect

# Step 3: Install Claude Code
npm install -g @anthropic-ai/claude-code
claude auth login

# Step 4: Clone and build
git clone https://github.com/cdwaage/ace-sandbox.git
cd ace-sandbox
docker build -t ace-sandbox:latest .
cp .env.example .env

# Step 5: Run
./run-sandbox.sh --skill web-builder "Build an e-commerce site for a bakery"

undefinedWindows notes:undefined

• Docker Desktop with WSL2 backend also works — just make sure you run commands from inside WSL, not PowerShell
• Your Claude credentials from VS Code carry over to WSL if ~/.claude is accessible
• Output files land in the WSL filesystem — access them from Windows at \\wsl$\Ubuntu\home\<user>\ace-sandbox\sandbox-output\

Requirements

• Docker (Docker Desktop on macOS/Windows, docker.io on Linux)
• Claude Max subscription OR ANTHROPIC_API_KEY
• Node.js 18+ (for Claude Code CLI)
• Optional: GEMINI_API_KEY for AI image generation (Nano Banana)