Cloud Sandbox

Fully isolated cloud development environments. Each user gets their own Docker container with a browser, terminal, file system, and HTTP server capability.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Orchestrator                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ BrowserClient│  │TerminalServer│  │  FileServer  │          │
│  │ (WS proxy)   │  │ (docker exec)│  │ (docker exec)│          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
└─────────┼─────────────────┼─────────────────┼──────────────────┘
          │                 │                 │
          │ WebSocket       │ docker exec     │ docker exec
          │ (port 9222)     │                 │
          ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Docker Container (per user)                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                     Supervisor                              ││
│  │  ┌─────────────────┐                                        ││
│  │  │  browser-server │ ◄── Playwright + Chromium              ││
│  │  │  (port 9222)    │     (fully isolated)                   ││
│  │  └─────────────────┘                                        ││
│  └─────────────────────────────────────────────────────────────┘│
│  User workspace: /home/sandbox/workspace                        │
│  Memory limit: 512MB | CPU limit: 1 core | PID limit: 256       │
└─────────────────────────────────────────────────────────────────┘

Security Model

• Full isolation: Each user gets their own Docker container
• No host access: Terminal and files operate entirely within the container
• Resource limits: Memory (512MB), CPU (1 core), PIDs (256) per container
• No privilege escalation: --security-opt=no-new-privileges
• Browser isolation: Chromium runs inside the container, not on host

Quick Start

# Install dependencies
npm install

# Build the sandbox Docker image
make sandbox-build

# Start development (orchestrator + frontend)
npm run dev

Open http://localhost:5173 for the frontend.

API Endpoints

REST API (port 8000)

# List instances
GET /api/instances

# Create instance
POST /api/instances
{ "userId": "user@example.com", "name": "my-sandbox" }

# Delete instance
DELETE /api/instances/:id

# Browser control
POST /api/instances/:id/browser
{ "action": "navigate", "url": "https://example.com" }
{ "action": "click", "x": 100, "y": 200 }
{ "action": "type", "text": "hello" }
{ "action": "scroll", "deltaY": 100 }

# File operations (within ~/workspace)
GET /api/instances/:id/files?path=/
GET /api/instances/:id/files/path/to/file
PUT /api/instances/:id/files/path/to/file
{ "content": "file contents" }
DELETE /api/instances/:id/files/path/to/file

# Stats
GET /api/stats

WebSocket Endpoints

ws://localhost:8000/ws/browser/:instanceId   # Browser frame stream
ws://localhost:8000/ws/terminal/:instanceId  # Terminal I/O
ws://localhost:8000/ws/files/:instanceId     # File change notifications

User HTTP Proxy

http://localhost:8000/proxy/:instanceId/:port/...
ws://localhost:8000/proxy/:instanceId/:port/...

Project Structure

cc-prod/
├── packages/
│   ├── orchestrator/     # Main backend server
│   │   └── src/
│   │       ├── index.ts            # Fastify server + WebSocket handling
│   │       ├── container-manager.ts # Docker container lifecycle
│   │       ├── browser-client.ts   # Connects to container browser servers
│   │       ├── terminal-server.ts  # Terminal via docker exec
│   │       ├── file-server.ts      # Files via docker exec
│   │       └── proxy-server.ts     # HTTP proxy for user apps
│   │
│   ├── frontend/         # React frontend
│   │   └── src/
│   │       ├── App.tsx
│   │       └── components/
│   │           ├── BrowserStream.tsx
│   │           ├── Terminal.tsx
│   │           └── FileExplorer.tsx
│   │
│   ├── sandbox/          # Docker container for user environments
│   │   ├── Dockerfile
│   │   ├── browser-server.ts  # Playwright server (runs inside container)
│   │   └── package.json
│   │
│   └── shared/           # Shared TypeScript types
│       └── src/index.ts
│
├── package.json          # Workspace root
├── turbo.json            # Turborepo config
├── Makefile              # Build commands
└── docker-compose.yml    # Production deployment

Container Features

Each sandbox container includes:

• Node.js 20 - JavaScript/TypeScript runtime
• Python 3 - With pip and venv support
• Chromium - Full browser with Playwright control
• Git - Version control
• Build tools - gcc, g++, make
• Editors - vim, nano

Resource Usage

Users	Containers	RAM Needed	Recommended Server
10	10	~5GB	8GB VPS
50	50	~25GB	32GB dedicated
100	100	~50GB	64GB dedicated

Development

# Build all packages
npm run build

# Run in development mode (with hot reload)
npm run dev

# Rebuild sandbox Docker image after changes
make sandbox-build

Deployment

# Build for production
npm run build

# Build Docker images
make sandbox-build

# Start with Docker Compose
docker-compose up -d