The sandbox gives the built-in Agent an isolated execution environment: run commands, read and write files, and host long-lived processes. Everyday Agent use cases (data processing, file operations, running user code, hosting stdio MCP) all rely on it.
Once the sandbox is enabled, the built-in Agent automatically gains six tools — no need to wire each one into the pipeline.
| Tool | Purpose |
|---|
exec | Run shell commands inside the sandbox |
read | Read workspace files |
write | Create or overwrite files |
edit | Modify files via string replacement |
glob | Find files by glob pattern |
grep | Search file contents by regex |
exec runs inside the sandbox container; the other five operate directly on the host directory mapped to /workspace.
These tools target the built-in Agent. When using external runners such as Dify, n8n, Langflow, or Coze, use that platform’s own tool mechanism.
Sandbox Scope
The pipeline’s AI configuration lets you choose how the sandbox is shared across messages. The default “per chat” works for most cases.
| Scope | Template | Shared across |
|---|
| Global | {global} | All users share one sandbox |
| Per chat (default) | {launcher_type}_{launcher_id} | Same group or DM shares one |
| Per user | {launcher_type}_{launcher_id}_{sender_id} | Each member in a group is isolated |
| Per conversation | {launcher_type}_{launcher_id}_{conversation_id} | Isolated by conversation |
| Per message | {query_id} | Fully stateless |
Commands within the same scope share filesystem state. Choose “per message” for full isolation.
Lifecycle
| Condition | Behavior |
|---|
| Idle for more than 5 minutes | Cleaned up automatically |
| Box-managed processes running (e.g. stdio MCP) | Kept alive until those processes exit |
persistent: true configured | Never cleaned up automatically |
Quick Start
- Prepare the backend: install Docker locally, or pick Nsjail / E2B
- Edit
config.yaml:
box:
enabled: true
backend: 'local'
local:
host_root: './data/box'
- Start LangBot: the sandbox is enabled automatically
- In the pipeline, select the built-in Agent plus a model that supports function calling
The Agent will then automatically receive the six tools. See Sandbox Configuration for details.
Disabling the Sandbox
Set box.enabled: false. Everything that depends on the sandbox (built-in tools, Skill create/edit/activate, stdio MCP) is disabled together; MCP servers in http/sse mode are unaffected.
Next Steps
