Execution Sandbox

By default, bash and command tools run directly on the local filesystem. BMO supports two isolation modes:

• sandbox_mode: staged — captures all file writes as reviewable diffs before applying
• sandbox.backend: docker, ssh, or buildkit — routes command execution to an isolated environment

Sandbox mode

[options]
sandbox_mode = "direct"   # default: writes are applied immediately
# sandbox_mode = "staged" # capture writes as diffs for review

Docker backend

[options]
sandbox_mode = "direct"

[options.sandbox]
backend = "docker"

[options.sandbox.docker]
image = "ubuntu:24.04"
extra_args = ["--network=none"]

All bash tool calls are routed through docker run with the specified image. The working directory is mounted into the container.

SSH backend

[options.sandbox]
backend = "ssh"

[options.sandbox.ssh]
host = "build-server.example.com:22"
user = "ci"
key_file = "~/.ssh/id_ed25519"
known_hosts_file = "~/.ssh/known_hosts"

All bash tool calls are forwarded to the SSH host. The working directory is synchronized before execution.

BuildKit backend

[options.sandbox]
backend = "buildkit"

[options.sandbox.buildkit]
endpoint = "tcp://buildkit.example.com:1234"
image = "golang:1.26"
# buildctl_path = "/usr/local/bin/buildctl"
# max_parallel = 4
# queue_capacity = 32

BuildKit routes commands through buildctl using the configured image and working directory as build context. The current slice is validation-first: it provides bounded concurrent lane primitives for remote build/test capacity, but it does not yet add background shell parity or remote agent workspaces.

Inspecting sandbox posture

Use the shared posture surfaces when you need to confirm what BMO will do without starting Docker, dialing SSH, invoking BuildKit, or running a command:

bmo config show-sandbox

The same read model backs the TUI /sandbox slash command and the read-only sandbox_status agent tool. The report includes:

• backend readiness and bounded degraded/unavailable reasons
• direct vs staged file-write mode
• whether background shell execution is supported for the selected backend
• validation-lane summary when a validation fabric run is attached
• recent metadata-only sandbox.* events and action/outcome counts

Remote backends fail closed when required configuration is missing. Docker requires an image. BuildKit requires endpoint and image. SSH requires host and user; omitted key or known-hosts paths are reported as degraded defaults rather than hidden assumptions.

The recent-event ring is process scoped and metadata only. It stores bounded enums, timing, exit class, and hashed workspace identifiers; it does not store raw commands, argv, environment values, stdout, stderr, SSH hosts, key paths, or working directories.

Choosing a backend

Backend	Use case
local (default)	Development, trusted environments
docker	Isolation without network access; consistent build environments
ssh	Remote build servers, cloud VMs, air-gapped environments
buildkit	Remote BuildKit workers, concurrent validation lanes, cache-aware builds
staged mode	Review all file writes before they land on disk

Visual: execution boundary map

Execution boundaries

Local directFastest path; commands and writes affect the working tree directly.

Staged writesFile mutations are captured as reviewable diffs before landing.

Docker / SSH / BuildKitProcess execution moves into a container, remote host, or BuildKit worker boundary.

Sandbox choice controls where processes run and how writes are reviewed; it does not replace prompt/tool permissions.