feat(tools): add "sandbox" toolset to run code snippets in an ephemeral, isolated container

[dwin-gharibi]

Closes #3638

---

Summary

Adds a new built-in toolset, sandbox, that runs a code snippet (python, node, or bash) inside an ephemeral, isolated container and returns stdout, stderr, and the exit code. Every run is disposable (--rm), resource-limited (memory / CPU / PID), time-bounded, and network-disabled by default.

Tool: run_code(language, code, timeout_seconds?, network?).

Motivation

Agents often need to run code — compute a result, transform data, verify an approach — not just read/write files. Today the only option is shell, which runs on the host with full access. The sandbox runs untrusted / model-generated code in a disposable, isolated container instead. It fits docker-agent naturally, since a container runtime is already the environment it ships on.

Works with docker or other runtimes

Execution goes through an injectable Executor, and the default one auto-detects a docker-compatible CLI in order: docker → podman → nerdctl (they share run --rm -i --network none … syntax). If none is present, run_code returns a clear error.

What changed

File	Change
pkg/tools/builtin/sandbox/sandbox.go	New. The toolset: run_code, pure buildRunArgs, Executor seam, runtime detection.
pkg/tools/builtin/sandbox/sandbox_test.go	New. Args construction, language aliasing, timeout capping, output formatting, and error paths (fake executor).
pkg/teamloader/toolsets/toolsets.go	Register the sandbox creator.
pkg/teamloader/toolsets/catalog.go	Add the sandbox catalog entry (required by the drift-guard test).
docs/configuration/tools/index.md	Add sandbox to the built-in toolsets table.
docs/tools/sandbox/index.md	New. Dedicated docs page.

Design for testability

The container command is a pure buildRunArgs function, and execution goes through an Executor interface. Tests cover argument construction, language aliasing, timeout capping, output formatting, and every error path with a fake executor — everything except the literal docker run, which needs a daemon (covered by CI/integration).

Example

The command it builds:

docker run --rm -i --memory 512m --cpus 1 --pids-limit 256 --network none python:3.12-slim python3 -

Tool output:

run_code(language="python", code="print(2 + 2)")

Exit code: 0

--- stdout ---
4

run_code (error)

Exit code: 1

--- stderr ---
SyntaxError: bad

Testing

go test ./pkg/tools/builtin/sandbox/ ./pkg/teamloader/toolsets/

• buildRunArgs (isolation flags, limits, image; --network none present by default and absent when network: true), language aliasing, run_code (success, non-zero exit, empty code, unknown language, timeout cap, executor error), and the tool/interface check.
• TestBuiltinToolsetsCatalogMatchesRegistry passes with sandbox in both registry and catalog.

All pass; gofmt -l and go vet clean. (CI runs task lint / task test.)

Safety / scope

• Isolated by default: --rm, --network none, --memory 512m, --cpus 1, --pids-limit 256, and a time limit (default 30s, capped 300s).
• network: true opts into a network only when the agent explicitly asks.
• Requires a container runtime at runtime; returns a clear error otherwise.
• v1 uses pinned per-language images with fixed limits; configurable images and limits are noted as future work.

[aheritier]

To discuss with the team but I don't think it would work well with sandboxes like sbx which are designed for such purpose. Here giving the choice to the Agent to use the sandbox tool is not very secure and will probably not be very efficient

[dwin-gharibi]

To discuss with the team but I don't think it would work well with sandboxes like sbx which are designed for such purpose. Here giving the choice to the Agent to use the sandbox tool is not very secure and will probably not be very efficient

You’re right @aheritier, I agree that giving the Agent full freedom to decide when to use the sandbox might not be the best approach from a security and efficiency perspective, especially since sandboxes like sbx are already designed specifically for this purpose.

With the current implementation, the user can only choose whether the sandbox should be enabled or disabled globally for all cases. However, there are scenarios where the user may not enable the sandbox, but the Agent can determine that a specific command should still be executed inside a sandbox for security or isolation reasons.

Without having access to the sandbox tool at the Agent level, that kind of decision-making is not possible. The Agent would have no way to enforce isolation when it identifies a potentially risky operation.

So I think the question is more about finding the right balance: keeping user control over sandbox availability while allowing the Agent to request or require sandbox execution for specific actions when needed.

[dwin-gharibi]

To discuss with the team but I don't think it would work well with sandboxes like sbx which are designed for such purpose. Here giving the choice to the Agent to use the sandbox tool is not very secure and will probably not be very efficient

You’re right @aheritier, I agree that giving the Agent full freedom to decide when to use the sandbox might not be the best approach from a security and efficiency perspective, especially since sandboxes like sbx are already designed specifically for this purpose.

With the current implementation, the user can only choose whether the sandbox should be enabled or disabled globally for all cases. However, there are scenarios where the user may not enable the sandbox, but the Agent can determine that a specific command should still be executed inside a sandbox for security or isolation reasons.

Without having access to the sandbox tool at the Agent level, that kind of decision-making is not possible. The Agent would have no way to enforce isolation when it identifies a potentially risky operation.

So I think the question is more about finding the right balance: keeping user control over sandbox availability while allowing the Agent to request or require sandbox execution for specific actions when needed.

Also, this is a first step toward enabling remote code execution for the Agent on cloud environments and adding broader execution support in the future. The goal is to build the foundation for the Agent to safely execute tasks across different environments with proper isolation and security controls.

This is also aligned with the approach used by projects like Crabbox, where the execution environment is treated as a separate capability that can be controlled and integrated by the Agent.

Please take some time to think about this approach with team and let me know whether you think we should continue with the implementation or reconsider the direction. However It's almost implemented and only needs triage.