Sandbox

📦

The sandbox is the isolated workspace where the agent does file and command-based work. It is what makes DeerFlow capable of real action, not just conversation.

The sandbox gives the Lead Agent a controlled environment where it can read files, write outputs, run shell commands, and produce artifacts. Without a sandbox, the agent can only generate text. With a sandbox, it can write and execute code, process data files, generate charts, and build deliverables.

Sandbox modes

DeerFlow supports four sandbox modes. Choose the one that fits your deployment:

LocalSandbox (default)

Commands run directly on the host machine’s filesystem. There is no container isolation.

Best for: trusted, single-user local development workflows.
Risk: the agent has access to the host filesystem. Use allow_host_bash: false (default) to prevent arbitrary command execution.


sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  allow_host_bash: false # default; set to true only for fully trusted workflows

Container-based AIO Sandbox

Commands run in an isolated container (Docker on Linux/Windows, or Apple Container on macOS). Each sandbox session gets a fresh container environment.

Best for: multi-user environments, production deployments, or any case where you want execution isolation.


sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
 
  # Optional: container image (default shown below)
  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
 
  # Optional: max concurrent containers (default: 3, LRU eviction when exceeded)
  replicas: 3
 
  # Optional: container name prefix (default: deer-flow-sandbox)
  container_prefix: deer-flow-sandbox
 
  # Optional: idle timeout in seconds (default: 600)
  idle_timeout: 600
 
  # Optional: custom mounts
  mounts:
    - host_path: /path/on/host
      container_path: /home/user/shared
      read_only: false
 
  # Optional: environment variables injected into the container
  environment:
    API_KEY: $MY_API_KEY

Install: cd backend && uv add 'deerflow-harness[aio-sandbox]'

E2B Cloud Sandbox

Commands run in an E2B cloud micro-VM. Each thread is bound to its own sandbox via metadata, so the same DeerFlow thread keeps reaching the same e2b sandbox even across gateway restarts and across processes. The cloud VM is reaped automatically by e2b once the configured idle timeout elapses.

Best for: hosted/serverless deployments, teams that do not want to operate Docker or Kubernetes themselves, workloads that need a real Jupyter kernel out of the box.
Trade-off: requires network access to the e2b control plane and an API key. Mounts are one-shot uploads at sandbox start (host bind-mounts are not possible because the sandbox lives in the cloud).


sandbox:
  use: deerflow.community.e2b_sandbox:E2BSandboxProvider
 
  # Required: e2b API key. Falls back to the E2B_API_KEY environment variable.
  api_key: $E2B_API_KEY
 
  # Optional: e2b sandbox template id (default: code-interpreter-v1)
  template: code-interpreter-v1
 
  # Optional: self-hosted e2b deployment domain
  # domain: e2b.dev
 
  # Optional: directory inside the sandbox that backs /mnt/user-data
  # (default: /home/user)
  home_dir: /home/user
 
  # Optional: server-enforced idle timeout in seconds (default: 600, max 86400).
  # The provider refreshes this on every release so warm sandboxes stay alive.
  idle_timeout: 600
 
  # Optional: max concurrent sandboxes per gateway process (default: 3).
  # When exceeded, the least-recently-used warm sandbox is killed.
  replicas: 3
 
  # Optional: one-shot upload of host files into the sandbox at start.
  # Read-only mounts are chmod'd to read-only after upload.
  mounts:
    - host_path: /path/on/host
      container_path: /home/user/shared
      read_only: false
 
  # Optional: environment variables forwarded to the sandbox on create.
  # Values starting with "$" are resolved from the host environment.
  environment:
    OPENAI_API_KEY: $OPENAI_API_KEY

Install: e2b-code-interpreter is already a core dependency of deerflow-harness, so no extra install step is needed — just provide your API key and switch the provider in config.yaml.

Get an API key at e2b.dev/dashboard and either set sandbox.api_key directly in config.yaml or export E2B_API_KEY in your .env.

Because e2b is a remote sandbox, DeerFlow’s /mnt/user-data virtual prefix is remapped onto home_dir (default /home/user) inside the cloud VM. Tools that read or write under /mnt/user-data/... continue to work transparently.

Provisioner-managed Sandbox (Kubernetes)

Each sandbox gets a dedicated Pod in a Kubernetes cluster, managed by the provisioner service. This provides the strongest isolation and is recommended for production environments with multiple concurrent users.


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

The provisioner service is included in docker/docker-compose-dev.yaml and manages the Pod and Service lifecycle for each sandbox ID.

Path mappings

The sandbox uses path mappings to bridge the host filesystem and the container’s virtual filesystem. Two key mappings are always configured:

Host path	Container path	Access
`skills/` (from `skills.path`)	`/mnt/skills` (from `skills.container_path`)	Read-only
`.deer-flow/threads/{thread_id}/user-data/`	`/mnt/user-data/`	Read-write

The skills directory is always mounted read-only. Threads write their working data (uploads, outputs, intermediate files) to /mnt/user-data/.

Custom mounts

You can add additional mounts for the local sandbox using the mounts: configuration:


sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  mounts:
    - host_path: /home/user/my-project
      container_path: /mnt/my-project
      read_only: true

Custom mount container_path values must not conflict with reserved prefixes: /mnt/skills, /mnt/acp-workspace, or /mnt/user-data.

Output truncation

The sandbox tools limit output size to keep the agent’s context manageable. These limits are configurable:


sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
 
  # bash uses middle-truncation (head + tail)
  bash_output_max_chars: 20000
 
  # read_file uses head-truncation
  read_file_output_max_chars: 50000
 
  # ls uses head-truncation
  ls_output_max_chars: 20000

Set to 0 to disable truncation.

Security

LocalSandbox

The LocalSandbox runs commands directly on the host. By default, the bash tool is disabled to prevent arbitrary host command execution. Enable it only for fully trusted, single-user workflows:


sandbox:
  allow_host_bash: true # Dangerous: grants the agent shell access to your machine

Even without bash, the agent can still read and write files through the dedicated file tools.

Container sandbox

Container-based sandboxes provide filesystem and process isolation. The agent cannot see or modify the host filesystem except through explicit mounts. The provisioner-managed mode adds a further layer: each thread gets its own isolated Pod.

Audit middleware

SandboxAuditMiddleware runs on every agent turn and records all sandbox operations. This provides an audit trail of what files were accessed and what commands were run during a session.

Tools Subagents