spark-sandbox

Instant, isolated development environments for DGX Spark with Claude Code integration.

Features

• Instant sandboxes - Full dev environment in seconds
• Multiple templates - Base, agent, desktop, and web configurations
• Claude Code integration - AI-assisted development built-in
• GPU passthrough - Full NVIDIA GPU access for desktop environments
• Dotfiles support - Bring your own configs via chezmoi
• Data persistence - Work persists across container restarts
• Port management - Automatic SSH and web port allocation

Quick Start

# Install
make install && make build-images

# Create and use a sandbox
box new myapp
box ssh myapp
box rm myapp -f

Installation

From Source

git clone https://github.com/spark-sandbox/spark-sandbox
cd spark-sandbox

# Build and install CLI
make install

# Build all Docker images
make build-images

Manual Build

# Build CLI only
go build -o ~/.local/bin/box ./cmd/box

# Build images individually
docker build -t spark-sandbox:base -f docker/Dockerfile.base docker/
docker build -t spark-sandbox:agent -f docker/Dockerfile.agent docker/
docker build -t spark-sandbox:web -f docker/Dockerfile.web docker/
docker build -t spark-sandbox:desktop -f docker/Dockerfile.desktop docker/

Templates

Template	Description	Size	Key Features
base	Full dev environment	2.56GB	Go, Node, Python, Rust, zsh
agent	AI-assisted coding	2.91GB	Base + Claude Code, tree, pandoc
web	Frontend development	2.94GB	Base + TypeScript, Vite, ESLint
desktop	Browser-based KDE GUI	6.25GB	Full GUI + dev stack + GPU

box new myapp                      # Uses base template
box new agent-work --template=agent
box new frontend --template=web
box new workstation --template=desktop

Commands

Sandbox Lifecycle

box new <name>           # Create sandbox
box ls                   # List all sandboxes
box start <name>         # Start stopped sandbox
box stop <name>          # Stop running sandbox
box restart <name>       # Restart sandbox
box rm <name> [-f]       # Remove sandbox (use -f for running)

Working with Sandboxes

box ssh <name>                    # SSH into sandbox
box exec <name> <cmd>             # Run command in sandbox
box logs <name> [-f]              # View container logs
box ports <name>                  # Show port mappings

Claude Code Integration

box claude <name>                 # Launch Claude Code attached
box new myapp --claude            # Create with OAuth session mounted

Desktop Environment

box new workstation --template=desktop
box desktop workstation           # Open in browser (http://localhost:3000)

Dotfiles

# Create sandbox with custom dotfiles
box new myapp --dotfiles=github.com/user/dotfiles

# Dotfiles are managed with chezmoi inside the container
box exec myapp chezmoi update

Utilities

box templates                     # List available templates
box status                        # Show system overview
box config                        # Show/edit configuration
box prune                         # Clean up stopped containers
box completion [bash|zsh|fish]    # Generate shell completions

Configuration

Config file: ~/.config/spark-sandbox/config.yaml

defaults:
  template: base
  ssh_port_range: [2200, 2299]
  web_port_range: [3000, 3999]

claude:
  oauth_session: ~/.claude
  auto_attach: true

dotfiles:
  repo: "github.com/myuser/dotfiles"  # Default dotfiles repo
  branch: "main"
  manager: "chezmoi"
  auto_apply: true

tailscale:
  auto_serve: true
  funnel_timeout: 8h

Port Allocation

Each sandbox gets dedicated ports automatically:

Service	Port Range	Example
SSH	2200-2299	ssh -p 2200 dev@localhost
Web	3000-3999	http://localhost:3000

Common container ports (80, 3000, 8000, 8080, 9000) are all mapped sequentially starting from the allocated web port.

View ports with box ls or box ports <name>.

Data Persistence

Sandbox data persists across stop/start cycles via Docker volumes.

# Data persists across restarts
box stop myapp && box start myapp

# Remove sandbox, keep data
box rm myapp -f

# Remove sandbox AND data
box rm myapp -f --volumes

Shell Completions

# Bash
box completion bash > ~/.local/share/bash-completion/completions/box

# Zsh
box completion zsh > ~/.zfunc/_box

# Fish
box completion fish > ~/.config/fish/completions/box.fish

Architecture

spark-sandbox/
├── cmd/box/               # CLI entrypoint
├── internal/
│   ├── cli/               # Cobra commands
│   ├── sandbox/           # Container management (Docker SDK)
│   └── config/            # Configuration handling
├── docker/
│   ├── Dockerfile.base    # Full dev environment
│   ├── Dockerfile.agent   # Claude Code optimized
│   ├── Dockerfile.web     # Frontend development
│   ├── Dockerfile.desktop # KDE GUI + dev stack
│   └── scripts/           # Container init scripts
└── scripts/               # Build and test scripts

Container Layout

• Base/Agent/Web: Ubuntu 24.04 with SSH, user dev
• Desktop: linuxserver/webtop (Ubuntu KDE), user abc
• Home: /home/dev (base/agent/web) or /config (desktop)
• Persistence: Named Docker volumes for home directories

Troubleshooting

Docker not running

Error: Docker is not running

Start Docker daemon: sudo systemctl start docker

Image not found

Error: image "spark-sandbox:base" not found

Build the image: docker build -t spark-sandbox:base -f docker/Dockerfile.base docker/

Or build all: make build-images

Port already in use

Error: failed to allocate SSH port

Another sandbox may be using that port. Check with box ls and stop unused sandboxes.

SSH connection refused

ssh: connect to host localhost port 2200: Connection refused

Wait a few seconds for the container to start SSH daemon, or check logs: box logs <name>

Permission denied in container

Files created on host-mounted volumes may have wrong permissions. Use sudo chown -R $(id -u):$(id -g) <path> on the host.

Dotfiles not applied

Check container logs for errors: box logs <name>

Ensure the dotfiles repo is public or you have SSH keys mounted for private repos.

Requirements

• Docker 20.10+
• Go 1.22+ (for building from source)
• NVIDIA Container Toolkit (for GPU passthrough in desktop template)

Development

make build          # Build CLI
make test           # Run tests
make lint           # Run linter
make dev            # Quick dev cycle

# Integration tests
./scripts/integration-test.sh

License

MIT