Sandbox
Tools that interact with external systems or execute code run inside isolated Docker containers (sandboxes). This prevents tools from accessing the host system, other containers, or internal networks unless explicitly allowed.
Which Tools Are Sandboxed
- execute_code — Always sandboxed. Code runs in an isolated Docker container with support for Python, JavaScript, Java, C++, Go, and R.
- Plugin tools — Always sandboxed. The plugin directory is mounted read-only in the container.
- Custom HTTP tools — Optionally sandboxed. By default, custom tools make HTTP requests directly from the application process. Enable sandboxing from the tool’s sandbox configuration page to run them in an isolated container instead.
Configuring Sandbox Settings
From the Tools page, click the gear icon in the Actions column to configure a tool’s sandbox settings.
Network Access
Controls whether the sandbox container can make outbound network connections.
- Enabled (default) — The container can reach external APIs and services. Required for tools that call external HTTP endpoints.
- Disabled — The container has no network access. Useful for code execution tools where you want to prevent data exfiltration.
File Access Mounts
Mount host directories into the sandbox container. One mount per line in path:mode format:
/data/uploads:ro— Mount/data/uploadsas read-only./data/output:rw— Mount/data/outputas read-write.
By default, no host directories are mounted into the sandbox. Add mounts only when tools need access to specific host files.
Custom Tool Sandboxing
For custom HTTP tools, an additional Run in Sandbox toggle controls whether the tool runs in a Docker container at all. When enabled, the tool’s HTTP request is executed inside an isolated container rather than directly from the application process.
This is useful for custom tools that call untrusted or third-party APIs where you want network-level isolation.
Technical Details
Sandbox implementation — Sandboxed execution uses llm_sandbox with Docker. Each tool invocation gets its own short-lived container based on the teamwebai-sandbox image. The tool’s logic is serialised into a self-contained Python script, injected into the container, and executed. Results are returned via stdout JSON.
Configuration scoping — Sandbox settings are stored globally (applying to all projects) and can be overridden per-project. At execution time, the system checks for a project-specific configuration first, then falls back to the global configuration.
Plugin sandbox context — When a plugin tool runs in a sandbox, it receives a SandboxToolContext — a lightweight context with plain dictionary data instead of live database sessions and service objects. The plugin directory is mounted read-only at /plugin in the container.