en usage sandbox config

Sandbox Configuration

Sandbox settings are owned by the LangBot main process; Box Runtime performs the actual execution. For most deployments, you only need to choose a backend, set the workspace directory, and pick a security profile.

Note

All box.* settings on this page live in data/config.yaml. See System Environment Settings for the file's location and how it's loaded.

Recommended Configuration

box:
  enabled: true
  backend: 'local'        # auto-pick from Docker / Nsjail
  local:
    profile: 'default'
    host_root: './data/box'
    skills_root: 'skills'
  docker:
    cpu_limit_enabled: true

• enabled: master switch. When false, all Box-dependent features are disabled (sandbox tools, skill add/edit, stdio MCP hosting).
• backend: see "Backend Selection" below.
• local.profile: security profile — controls network, mounts, and resource limits.
• local.host_root: host workspace directory, mapped to /workspace inside the sandbox.
• local.skills_root: skill package directory; relative paths resolve under host_root (defaults to host_root/skills).
• docker.cpu_limit_enabled: whether Docker sandbox containers get a CPU limit; set to false to omit docker run --cpus while keeping memory and PID limits.

Note

Skills are loaded only from the Box-managed skill store. When Box Runtime or the backend is unavailable, the skill list is empty and create/edit/register_skill are disabled — there's no fallback to data/skills/.

Backend Selection

The sandbox can run on local containers or in the cloud. box.backend picks which:

backend	Where it runs	Behavior
local (default)	Local containers	Auto-pick from Docker / Nsjail (Docker preferred)
docker	Local containers	Force Docker; requires the Docker daemon
nsjail	Local containers	Force Nsjail (Linux only); no custom image support
e2b	Cloud	Use E2B cloud sandbox; requires API key

local is shorthand for "auto-pick", not a fourth backend sitting next to docker/nsjail. The local backends (local/docker/nsjail) share the box.local.* config section; the cloud backend uses box.e2b.*.

Note

backend is a hard selection. Setting docker and finding Docker unavailable does not fall back to Nsjail or E2B — only local auto-fans-out.

BOX__BACKEND environment variable overrides box.backend (highest priority).

Security Profiles

box.local.profile controls network, mounts, and resource limits for local backends:

Profile	Network	Mounts	Resources	When to use
default	Off	Read-write	Default limits	Default choice
offline_readonly	Off	Read-only	Stricter	Reading untrusted files
network_basic	Basic network	Read-write	Default limits	API access or dependency install
network_extended	Full network	Read-write	Relaxed	Development, debugging, complex tasks

Prefer least privilege: skip the network unless you need it (default / offline_readonly); only add necessary directories to allowed_mount_roots.

Local Backend Configuration (box.local.*)

The local backends (local / docker / nsjail) share these settings:

Setting	Default	Notes
local.profile	default	See "Security Profiles" above
local.image	empty	Docker-only custom image; empty = use profile default
local.host_root	./data/box	Host workspace base, mapped to /workspace inside the sandbox
local.default_workspace	empty	Default workspace name; empty = <host_root>/default
local.skills_root	skills	Skill package directory; relative paths resolve under host_root
local.allowed_mount_roots	[host_root]	Allowlist of host directories the Agent can mount
local.workspace_quota_mb	null	Workspace disk quota (MB); null = use profile default
default_memory_mb	1536	Memory limit for each MCP stdio process (MB); overridable via BOX__DEFAULT_MEMORY_MB

Box Sandbox Memory Configuration

box.default_memory_mb sets the nsjail cgroup memory cap for every stdio-mode MCP server process.

Setting	Notes	Default
box.default_memory_mb	MCP process memory cap (MB)	1536

Can be set in config.yaml or via the BOX__DEFAULT_MEMORY_MB environment variable.

When to adjust:

• Node.js MCP servers (launched via npx/bunx): V8 + WebAssembly module initialisation needs significant memory; keep at ≥ 1536 MB
• Python MCP servers (launched via uvx): 512 MB is usually enough, but the default is fine too
• When memory is exhausted, the process is forcibly killed (return_code=137), logged as "Box managed process exited unexpectedly"

Per-server override: Set box.memory_mb in the individual MCP server config to override the global default.

Docker Backend Configuration (box.docker.*)

Setting	Default	Notes
docker.cpu_limit_enabled	true	Docker backend only. When false, sandbox containers start without --cpus; --memory and --pids-limit still apply.

Cloud Backend Configuration (box.e2b.*)

Configure after setting backend: 'e2b':

Setting	Default	Notes
e2b.api_key	empty	E2B API key; can also be set via E2B_API_KEY
e2b.api_url	empty	Self-hosted E2B endpoint; can also be set via E2B_API_URL
e2b.template	empty	Default E2B template ID

E2B doesn't need Docker or Nsjail on the host — every execution goes through the remote sandbox.

Docker Compose Deployment

In Docker Compose, sandbox settings live on the langbot service. LangBot forwards them to langbot_box via INIT RPC at startup.

services:
  langbot_box:
    image: rockchin/langbot:latest
    container_name: langbot_box
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]

  langbot:
    image: rockchin/langbot:latest
    volumes:
      - ./data:/app/data
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__DOCKER__CPU_LIMIT_ENABLED=${LANGBOT_BOX_DOCKER_CPU_LIMIT_ENABLED:-true}

Warning

langbot_box needs the Docker daemon. Only mount docker.sock in trusted environments, and keep the Box root path identical on the host and inside the langbot_box container.

To point LangBot at an externally-managed Box Runtime (e.g. a remote host), use box.runtime.endpoint:

box:
  runtime:
    endpoint: 'ws://192.168.1.10:5410'

Environment Variables

Environment variable	Maps to
BOX__ENABLED	box.enabled
BOX__BACKEND	box.backend
BOX__LOCAL__PROFILE	box.local.profile
BOX__LOCAL__IMAGE	box.local.image
BOX__LOCAL__HOST_ROOT	box.local.host_root
BOX__LOCAL__DEFAULT_WORKSPACE	box.local.default_workspace
BOX__LOCAL__SKILLS_ROOT	box.local.skills_root
BOX__LOCAL__ALLOWED_MOUNT_ROOTS	box.local.allowed_mount_roots, comma-separated
BOX__LOCAL__WORKSPACE_QUOTA_MB	box.local.workspace_quota_mb
BOX__DEFAULT_MEMORY_MB	box.default_memory_mb
BOX__DOCKER__CPU_LIMIT_ENABLED	box.docker.cpu_limit_enabled
BOX__E2B__API_KEY	box.e2b.api_key
BOX__E2B__API_URL	box.e2b.api_url
BOX__E2B__TEMPLATE	box.e2b.template

Note

Don't set BOX__* or LANGBOT_BOX_* on the langbot_box service — Box Runtime doesn't read them directly. Its configuration arrives over INIT RPC from LangBot.