Sandbox Manager

A web-based orchestration platform for managing Claude Code sandbox containers with terminal access, MCP (Model Context Protocol) configuration, and LLM routing through LiteLLM.

Quick Start

Access URL: https://sandbox.haiven.local

Navigate to https://sandbox.haiven.local
Log in with your credentials
Click "Create New Sandbox" to launch a Claude Code container
Configure MCP servers and LLM settings
Access terminal through the web interface

Architecture

Component	Details
Container	`sandbox-manager`
Port	`8900`
Networks	`web`, `backend`, `sandbox`
Domain	`sandbox.haiven.local`
Framework	Next.js 14 + TypeScript
Database	SQLite
Terminal	xterm.js + WebSocket

Key Features

Container Lifecycle Management - Create, start, stop, delete Claude Code containers
Web Terminal Access - Browser-based terminal via xterm.js
MCP Configuration - Auto-generated .mcp.json per sandbox
LLM Routing - All requests routed through LiteLLM proxy
JWT Authentication - Secure session management
Sandbox Isolation - ICC=false network for container isolation

Configuration

Environment Variables

# Required
JWT_SECRET: "${JWT_SECRET}"
SANDBOX_USERNAME: "${SANDBOX_USERNAME:-admin}"
SANDBOX_PASSWORD_HASH: "${SANDBOX_PASSWORD_HASH}"

# Service URLs
LITELLM_URL: "http://10.0.0.42:4000"
LITELLM_API_KEY: "${LITELLM_API_KEY}"
GITLAB_URL: "https://gitlab.haiven.local"
GITLAB_PAT: "${GITLAB_PAT}"

# Container ExtraHosts
LITELLM_HOST: "10.0.0.42"
MCP_SERVER_HOST: "10.0.0.42"
GITLAB_HOST: "10.0.0.42"

Volume Mounts

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro  # Docker API access
  - ./data:/data                                   # SQLite database
  - /mnt/projects:/mnt/projects:rw                 # Project files
  - /mnt/storage/repos:/mnt/storage/repos:rw       # Git repositories

API Reference

Base URL: https://sandbox.haiven.local/api

Endpoint	Method	Description
`/health`	GET	Health check
`/auth/login`	POST	Authenticate user
`/auth/logout`	POST	End session
`/containers`	GET	List all containers
`/containers`	POST	Create new container
`/containers/{id}`	GET	Get container details
`/containers/{id}`	DELETE	Delete container
`/containers/{id}/start`	POST	Start container
`/containers/{id}/stop`	POST	Stop container
`/files/browse`	GET	Browse file system

Example: Create Container

curl -X POST https://sandbox.haiven.local/api/containers \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-sandbox",
    "project_path": "/mnt/projects/my-app",
    "model": "claude-sonnet-4-5-20250929",
    "mcp_preset": "development"
  }'

Service Management

# Start service
cd /mnt/apps/docker/ai/sandbox-manager
docker compose up -d

# View logs
docker logs -f sandbox-manager

# Stop service
docker compose down

Monitoring

Health Endpoint: https://sandbox.haiven.local/api/health

Prometheus Labels:
- prometheus.io/scrape=true
- prometheus.io/port=8900
- prometheus.io/path=/api/health

Integration Points

Service	Purpose
LiteLLM	LLM API gateway for model routing
GitLab	Repository access via MCP
Traefik	Reverse proxy with TLS
Prometheus	Metrics collection

Troubleshooting

Container Won't Start

Check Docker socket permissions
Verify project path exists
Check MCP configuration syntax

Terminal Disconnects

Container may have stopped
WebSocket connection timeout
Refresh browser tab

MCP Not Working

Verify .mcp.json in container
Check MCP server availability
Review container logs

Implementation Plans: /mnt/apps/src/sandbox-manager/plan/
Docker Compose: /mnt/apps/docker/ai/sandbox-manager/docker-compose.yml
Source Code: /mnt/apps/src/sandbox-manager/