Runtime Sandboxing

DgiDgi provides secure Docker-based sandboxing for all code execution in development previews and agent-driven workflows.

Docker Sandbox

Every subscription includes access to Docker Sandbox - secure, isolated containers for code execution. The platform uses a provider-agnostic architecture, currently powered by Fly.io microVMs.

Subscription Tiers

Plan	Monthly Hours	Max Concurrent	Custom Runtimes	Custom Domains
Free	10h	1	—	—
Pro	100h	3	—	—
Growth	500h	5	✓	✓
Enterprise	Unlimited	Unlimited	✓	✓

Available Sandbox Images

Image	Description	Pre-installed Tools
nodejs	Node.js development	Node.js 20, Bun, pnpm, TypeScript, ESLint, Prettier, Vite, Next.js, Jest, Vitest, Prisma
python	Python development	Python 3.12, uv, Poetry, FastAPI, Django, Flask, pandas, numpy, pytest, Anthropic/OpenAI SDKs
fullstack	Complete environment	All Node.js + Python tools combined
base	Minimal	curl, git, SSH only

Pre-installed Tools

Node.js Sandbox

• Runtimes: Node.js 20, Bun
• Package Managers: npm, pnpm, yarn
• Build Tools: TypeScript, tsx, ts-node, turbo, nx
• Frameworks: create-vite, create-next-app, create-react-app
• Testing: Jest, Vitest, Playwright
• Linting: ESLint, Prettier
• Database: Prisma, drizzle-kit
• Deployment: Vercel CLI, Netlify CLI, Wrangler (Cloudflare)
• Utilities: pm2, nodemon, concurrently, http-server

Python Sandbox

• Runtime: Python 3.12
• Package Managers: pip, uv, Poetry, PDM, Hatch
• Web Frameworks: FastAPI, Flask, Django, uvicorn
• Data Science: pandas, numpy, matplotlib, seaborn, scikit-learn
• AI/ML: Anthropic SDK, OpenAI SDK, LangChain, llama-index, transformers, torch
• Testing: pytest, pytest-asyncio, pytest-cov
• Linting: black, ruff, mypy
• Database: SQLAlchemy, psycopg2, Redis
• Utilities: httpx, requests, pydantic, rich, click, typer

Security Features

• Process Isolation: Each session runs in a dedicated microVM
• Binary Whitelisting: Only approved binaries execute
• Network Isolation: Configurable network access policies
• Execution Timeouts: 5 min for commands, 15 min for dev servers
• Resource Limits: CPU, memory, and process limits enforced
• Auto-cleanup: Containers automatically destroyed after session ends

Custom Runtimes (Growth/Enterprise)

Growth and Enterprise plans can configure custom runtimes:

Supported Runtime Types

Type	Description
flyio	Default - Fly.io microVMs (Docker Sandbox)
docker	Self-hosted Docker containers
kubernetes	Kubernetes pods
firecracker	Firecracker microVMs
gvisor	gVisor sandboxed containers
remote	Custom runtime API endpoint

Custom Runtime Configuration

// Runtime configuration
{
  name: "My Custom Runtime",
  type: "kubernetes", // or "docker", "firecracker", etc.
  endpoint: "https://runtime.example.com/api",
  auth: {
    token: "...",
    // or other auth config
  },
  capabilities: {
    supportsDocker: true,
    languages: ["node", "python", "go"],
    maxConcurrent: 10,
    memoryMb: 2048,
  },
  environmentsAllowed: ["dev", "staging"],
  requiresApprovalForProd: true,
  dnsConfig: {
    domain: "preview.example.com",
    useProjectSubdomains: true,
    forceTls: true,
  },
  containerIsolation: {
    enabled: true,
    networkMode: "bridge",
    resourceProfile: "standard",
    vpc: "vpc-12345",
  }
}

Environment Variables

Server Configuration

# Fly.io Sandbox Configuration
FLY_API_TOKEN_SANDBOXES=your-fly-token    # Dedicated token for sandboxes
FLY_API_TOKEN=your-fly-token              # Fallback token
FLY_SANDBOX_APP=dgidgi-sandboxes          # Fly.io app name
FLY_ORG_SLUG=your-org-slug                # Fly.io organization

# Docker Isolation
DOCKER_ENFORCE_HIGH_RISK=true             # Enforce Docker for risky commands
DOCKER_ENFORCE_TOOLS=bash,terminal.execute
DOCKER_CPU=1                              # CPU cores per container
DOCKER_MEM=512m                           # Memory limit
DOCKER_PIDS=100                           # Max processes
DOCKER_NETWORK=none                       # Network isolation (none/bridge)

Runtime Resolution Order

1. Editor-specific runtime (if configured)
2. Project default runtime (if set)
3. Custom tenant runtime (if Growth/Enterprise)
4. Platform Docker Sandbox (default)

Preview URLs

Each sandbox session gets a preview URL for web applications:

https://{sandbox-id}-{port}.fly.dev

Preview Security

• X-Frame-Options: SAMEORIGIN - Prevents clickjacking
• X-Robots-Tag: noindex - Prevents search engine indexing
• CORS restrictions - Only allow platform origin
• TTL caching - 5-minute config cache

Database Configuration

Runtime isolation settings are stored per tenant:

-- From runtime.schema.ts
CREATE TABLE tenant_runtimes (
  id VARCHAR(36) PRIMARY KEY,
  tenant_id VARCHAR(36) NOT NULL,
  name TEXT NOT NULL,
  type VARCHAR(20) NOT NULL,
  endpoint TEXT,
  auth JSONB,
  capabilities JSONB DEFAULT '{}',
  environments_allowed TEXT[],
  requires_approval_for_prod BOOLEAN DEFAULT FALSE,
  enabled BOOLEAN DEFAULT TRUE,
  dns_config JSONB DEFAULT '{}',
  container_isolation JSONB DEFAULT '{}',
  created_at TIMESTAMP DEFAULT NOW()
);

Building Custom Images

To build and push custom sandbox images:

# Login to Fly.io registry
fly auth docker

# Build all images
./docker/sandbox/build-push.sh

# Build specific image
./docker/sandbox/build-push.sh nodejs
./docker/sandbox/build-push.sh python
./docker/sandbox/build-push.sh fullstack

Available Dockerfiles

File	Image	Description
Dockerfile.base	dgidgi-sandbox-base	Minimal base image
Dockerfile.nodejs	dgidgi-sandbox-nodejs	Node.js development
Dockerfile.python	dgidgi-sandbox-python	Python development
Dockerfile.fullstack	dgidgi-sandbox-fullstack	Complete environment

Best Practices

Resource Limits by Plan

Sandbox resources are allocated based on your subscription tier:

Plan	CPU	Memory
Free	1 CPU	256MB RAM
Pro	1 CPU	512MB RAM
Growth	2 CPU	1GB RAM
Enterprise	Custom	Custom

For Developers

1. Use appropriate sandbox image for your project:

   • Web apps → nodejs
   • Data science → python
   • Full-stack → fullstack

2. Test in sandboxed environment:

   • Use preview URLs for testing
   • Don't rely on network access in previews
   • Keep commands within timeout limits

3. Handle secrets properly:

   • Use environment variables
   • Never hardcode credentials
   • Test redaction works correctly

Troubleshooting

Container startup failures

# Check Fly.io status
fly status -a dgidgi-sandboxes

# List machines
fly machines list -a dgidgi-sandboxes

# Check logs
fly logs -a dgidgi-sandboxes

Authentication errors

Ensure your environment variables are set:

# Check token is valid
curl -H "Authorization: Bearer $FLY_API_TOKEN_SANDBOXES" \
  https://api.machines.dev/v1/apps/dgidgi-sandboxes/machines

Network access blocked

If your command needs network access:

1. Check if it's really necessary
2. Request network access in runtime config
3. Use staging environment for network-dependent tests

Timeout exceeded

Commands have default timeouts:

• Regular commands: 60 seconds (configurable)
• Dev servers: 15 minutes
• Long-running tasks: Use terminal.spawn instead of terminal.execute