Sandbox Modes

Configure sandbox execution environments - local, Docker, or Kubernetes-based isolation

DeerFlow supports multiple sandbox modes for executing code and commands. Choose between local execution for simplicity, Docker for isolation, or Kubernetes for production scalability.

Overview

The sandbox system provides isolated execution environments for agent operations. All file operations, command execution, and code running happen within the sandbox.

Local Sandbox

Direct execution on host machine. Fast but no isolation.

Docker Sandbox

Containerized execution with full isolation. Recommended for development.

Kubernetes Sandbox

Pod-based execution managed by provisioner. Best for production.

Local Sandbox

The simplest mode - executes commands directly on the host machine.

Configuration

config.yaml

sandbox:
  use: src.sandbox.local:LocalSandboxProvider

Characteristics

Fast - no container overhead
Simple setup - no Docker required
No isolation - full host access
Security risk - agent can access all host files

Local sandbox is not recommended for production use. The agent has unrestricted access to your filesystem and can execute any command.

Use Cases

• Quick local development and testing
• Running in trusted environments
• Debugging without container complexity
• Limited resource environments

Docker Sandbox (AIO Sandbox)

Containerized execution using Docker or Apple Container (macOS). Provides isolation while maintaining good performance.

Basic Configuration

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider

This minimal configuration automatically:

• Starts a Docker container on port 8080
• Uses the default all-in-one sandbox image
• Mounts the skills directory
• On macOS: Prefers Apple Container if available, falls back to Docker

Advanced Configuration

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  
  # Custom container image
  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
  
  # Base port for sandbox containers
  port: 8080
  
  # Whether to automatically start containers
  auto_start: true
  
  # Container name prefix
  container_prefix: deer-flow-sandbox
  
  # Idle timeout (seconds) before sandbox is released
  # Set to 0 to disable timeout
  idle_timeout: 600
  
  # Additional volume mounts
  mounts:
    - host_path: /path/on/host
      container_path: /home/user/shared
      read_only: false
  
  # Environment variables injected into container
  # Variables starting with $ are resolved from host environment
  environment:
    NODE_ENV: production
    DEBUG: "false"
    API_KEY: $MY_API_KEY
    DATABASE_URL: $DATABASE_URL

Configuration Options

use · string · required

Must be src.community.aio_sandbox:AioSandboxProvider

image · string

Docker image to use. The default image works on both x86_64 and arm64 architectures.

port · integer · default: "8080"

Base port for sandbox containers. Each container uses an incremental port.

base_url · string

If set, uses an existing sandbox at this URL instead of starting a new container.

Example: http://localhost:8080

auto_start · boolean · default: "true"

Whether to automatically start Docker containers. Set to false if managing containers manually.

container_prefix · string · default: "deer-flow-sandbox"

Prefix for container names. Containers are named {prefix}-{thread_id}.

idle_timeout · integer · default: "600"

Idle timeout in seconds before sandbox is released (default: 10 minutes). Set to 0 to disable timeout.

mounts · array

Additional volume mounts to share directories between host and container.

Note: The skills directory is automatically mounted.

Each mount requires:

• host_path: Path on the host machine
• container_path: Path inside the container
• read_only: Whether the mount is read-only (default: false)

environment · object

Environment variables to inject into the sandbox container.

Values starting with $ are resolved from the host environment:

environment:
  API_KEY: $MY_API_KEY  # Reads from host's MY_API_KEY variable
  STATIC_VALUE: "foo"   # Literal value

Using Existing Sandbox

Connect to a pre-started sandbox instead of managing containers:

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  base_url: http://localhost:8080  # No container will be started

Start the sandbox manually:

docker run -d \
  --name deer-flow-sandbox \
  -p 8080:8080 \
  -v /path/to/skills:/mnt/skills:ro \
  enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

Platform-Specific Behavior

macOS

On macOS, DeerFlow automatically prefers Apple Container if available, with fallback to Docker:

1. Checks for Apple Container runtime
2. Falls back to Docker if not available

No configuration changes needed - the provider handles this automatically.

Linux

Uses Docker for containerization. Ensure Docker is installed and running:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Start Docker
sudo systemctl start docker

Windows

Requires Docker Desktop for Windows. Install from docker.com.

Ensure WSL 2 backend is enabled in Docker Desktop settings for best performance.

Volume Mounts

The Docker sandbox automatically mounts:

1. Skills directory: From skills.path to skills.container_path (read-only)
2. Thread workspace: Per-thread working directory
3. Custom mounts: Additional directories specified in mounts

config.yaml

skills:
  path: /absolute/path/to/skills  # Host path
  container_path: /mnt/skills     # Container path

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  mounts:
    # Additional custom mount
    - host_path: /home/user/data
      container_path: /data
      read_only: true

Environment Variables in Container

Inject environment variables into the sandbox:

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  environment:
    # Static values
    NODE_ENV: production
    DEBUG: "false"
    
    # Resolved from host environment
    OPENAI_API_KEY: $OPENAI_API_KEY
    DATABASE_URL: $DATABASE_URL
    
    # Mix of both
    API_URL: https://api.example.com
    API_KEY: $API_KEY

Environment variables prefixed with $ are resolved from the host environment when DeerFlow starts.

Kubernetes Sandbox (Provisioner)

Production-grade sandbox using Kubernetes pods managed by a provisioner service. Each sandbox_id gets a dedicated pod.

Configuration

config.yaml

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

Architecture

┌─────────────────┐
│   DeerFlow      │
│   Backend       │
└────────┬────────┘
         │
         │ HTTP API
         ▼
┌─────────────────┐
│  Provisioner    │
│   Service       │
└────────┬────────┘
         │
         │ Kubernetes API
         ▼
┌─────────────────┐
│   k3s/k8s       │
│   Cluster       │
│                 │
│ ┌─────────────┐ │
│ │  Pod 1      │ │
│ │ (thread-1)  │ │
│ └─────────────┘ │
│ ┌─────────────┐ │
│ │  Pod 2      │ │
│ │ (thread-2)  │ │
│ └─────────────┘ │
└─────────────────┘

Characteristics

Full isolation - each thread gets its own pod
Scalable - handles many concurrent threads
Resource limits - CPU and memory controls
Production-ready - managed lifecycle
Complex setup - requires Kubernetes and provisioner

Use Cases

• Production deployments
• Multi-tenant environments
• High concurrency requirements
• Environments requiring strict isolation
• Cloud deployments

Provisioner Setup

The provisioner is a separate service that manages Kubernetes pods. See the provisioner documentation for setup instructions.

Comparison Matrix

Feature	Local	Docker	Kubernetes
Isolation	❌ None	✅ Container	✅✅ Pod
Setup Complexity	✅ Simple	⚠️ Moderate	❌ Complex
Performance	✅✅ Fast	✅ Good	⚠️ Moderate
Scalability	⚠️ Limited	✅ Good	✅✅ Excellent
Security	❌ Low	✅ High	✅✅ Highest
Resource Control	❌ No	⚠️ Basic	✅ Advanced
Production Ready	❌ No	⚠️ Yes	✅ Yes

Recommendations

Development

Use Docker sandbox for the best balance of isolation and convenience:

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider

Production (Single-user)

Use Docker sandbox with explicit configuration:

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  idle_timeout: 1800  # 30 minutes
  environment:
    NODE_ENV: production

Production (Multi-tenant)

Use Kubernetes sandbox with provisioner:

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

Quick Testing

Use local sandbox for rapid iteration:

sandbox:
  use: src.sandbox.local:LocalSandboxProvider

Never use local sandbox with untrusted input or in production.

Troubleshooting

Docker container fails to start

Check Docker is running and accessible:

# Check Docker status
docker ps

# Pull the sandbox image
docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

# Test manual start
docker run -p 8080:8080 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

Permission denied on volume mounts

Ensure the host paths exist and have correct permissions:

# Check path exists
ls -la /path/to/mount

# Fix permissions
chmod 755 /path/to/mount

Environment variables not resolved

Verify environment variables are set on the host:

# Check variable is set
echo $MY_API_KEY

# Add to .env if missing
echo "MY_API_KEY=value" >> .env

Container idle timeout too aggressive

Increase the idle timeout or disable it:

sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  idle_timeout: 3600  # 1 hour
  # OR
  idle_timeout: 0     # Disable timeout

Next Steps

Skills Configuration

Configure skills and MCP servers

Tools Reference

Explore available tools