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