Skip to main content

​
Overview

The Local Docker provider is the default execution backend for Nadoo Sandbox. It runs code in isolated Docker containers on your local machine or server.

​
Requirements

  • Docker Engine 20.10+
  • Docker Daemon running and accessible

​
Configuration

​
Environment Variables

# Docker socket path (default: /var/run/docker.sock)
DOCKER_HOST=unix:///var/run/docker.sock

# Enable warm pool for faster execution
WARM_POOL_ENABLED=true

# Number of pre-warmed containers per runtime
WARM_POOL_SIZE_PER_RUNTIME=3

​
Features

​
Warm Pool Integration

Local Docker provider integrates with the Warm Pool system for optimized cold start times:
  • Pre-warmed containers ready for immediate execution
  • ~50-100ms cold start latency (vs 2-5s without warm pool)
  • Automatic container recycling and health checks

​
Security Isolation

Each execution runs in a fully isolated container with:
  • Read-only root filesystem
  • No network access (unless explicitly enabled)
  • Resource limits (CPU, memory, disk)
  • Seccomp and AppArmor profiles

​
Usage

​
Basic Execution

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello from Docker!\")",
    "language": "python"
  }'

​
Explicit Provider Selection

curl -X POST http://localhost:8002/api/v1/execute \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "console.log(\"Hello!\")",
    "language": "javascript",
    "provider": "local_docker"
  }'

​
Container Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Request   │────▶│  Warm Pool  │────▶│   Execute   │
└─────────────┘     │   Check     │     │    Code     │
                    └──────┬──────┘     └──────┬──────┘
                           │                   │
                    ┌──────▼──────┐     ┌──────▼──────┐
                    │   Create    │     │   Reset &   │
                    │  Container  │     │   Return    │
                    └─────────────┘     └─────────────┘
  1. Request arrives at the executor
  2. Check warm pool for available container
  3. If available, use pre-warmed container; otherwise create new
  4. Execute code in isolated environment
  5. Reset container state and return to pool (if warm pool enabled)

​
Performance

MetricWithout Warm PoolWith Warm Pool
Cold Start2-5 seconds50-100ms
Execution Overhead~500ms~20ms
Container ReuseNoYes

​
Troubleshooting

​
Docker Socket Permission

If you encounter permission errors: 
sudo chmod 666 /var/run/docker.sock
# Or add user to docker group
sudo usermod -aG docker $USER

​
Container Resource Limits

Adjust container limits if execution fails: 
SANDBOX_MEMORY_LIMIT=512m
SANDBOX_CPU_LIMIT=1.0
SANDBOX_TIMEOUT=30