LangBot

---
title: "Sandbox"
description: "LangBot sandbox (Box Runtime) gives the built-in Agent an isolated environment to run commands and edit files safely."
---

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.

## Built-in Tools

| 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`.

<Note>
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.
</Note>

## 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 |

<Warning>
Commands within the same scope share filesystem state. Choose "per message" for full isolation.
</Warning>

## 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

1. **Prepare the backend**: install Docker locally, or pick Nsjail / E2B
2. **Edit `config.yaml`**:
   ```yaml
   box:
     enabled: true
     backend: 'local'
     local:
       host_root: './data/box'
   ```
3. **Start LangBot**: the sandbox is enabled automatically
4. **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](./config) 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

- [Sandbox Configuration](./config) — backends, security profiles, mounts, environment variables
- [Runtimes & Extensions Compared](./runtime-relationships) — how the sandbox, Skills, MCP, and plugins divide responsibilities