mcp-sandbox

module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: Apache-2.0

README

🤖 AI-Generated Content — The content of this repository, including all source code, documentation, and configuration files, has been generated by an artificial intelligence assistant or created using artificial intelligence assistant. While efforts have been made to ensure correctness and security, the code should be reviewed before use in any production environment.

mcp-sandbox

CI Release License MCP-Server Go Reference Go Version Coverage gosec govulncheck gremlins

CI gates — enforced by the live CI badge above (green only when every job passes): unit tests with coverage ≥ 95% · gosec · govulncheck · go-arch-lint · gremlins mutation ≥ 80% · gitleaks secret scan.

Platforms: Linux (Docker) · macOS (Docker, or Seatbelt sandbox-exec without a daemon)

A Local (stdio-only) MCP server that gives a model-host client (such as opencode) a safe, isolated environment to run arbitrary commands — a drop-in replacement for the host shell.

Instead of letting the model use the host shell directly, the model drives mcp-sandbox: for each session it provisions a per-session, isolated Docker container with the required directories mounted in, executes arbitrary commands inside that container, and destroys it via explicit sandbox_destroy / sandbox_destroy_all (per-session and ephemeral, but cleanup is explicit — there is no automatic GC). Security is the top priority — the sandbox is more restrictive than the host, never less.

  • MVP scope: the Docker backend, plus an experimental macOS sandbox-exec (Seatbelt) backend (implemented — portable core wired + darwin log stream tailer; real-macOS verification via the darwin e2e, see macOS driver). Apple Container and other backends are designed for but not yet implemented.
  • Deployment: Local / stdio-only. No HTTP, no observability endpoint, no container image.

Table of contents

Features

  • Per-session, isolated, ephemeral Docker sandboxes.
  • Execute arbitrary commands inside the sandbox (scalar command executed via the profile-configured shell — no shell-string concatenation).
  • The session cwd is mounted 1:1 at the same absolute path (read-only by default; rw opt-in via the profile's cwd.mode); files come from the image, the host, or the runtime — mount + exec is the core mechanism.
  • Operator-authored sandbox profiles (Phase 7): the image, env, mounts, network, cgroup limits, user and sudo are declared in read-only YAML profiles under SANDBOX_PROFILES_DIR, referenced by name on sandbox_create — no per-request knobs, no profile create/edit/delete tools.
  • Hardened by default: read-only rootfs, drop-all capabilities, no-new- privileges, seccomp, non-root user, bounded resources, tmpfs working dir, auto-remove.
  • Immutable Isolation policy the caller cannot weaken.
  • Secret-safe output: a single redaction layer hides secret:true fields from all output and logs.
  • Live streaming output: long-running tools (starting with sandbox_exec) emit notifications/progress so the model-host sees command output and the call parameters as they run — additive, redacted and ANSI-sanitized (see SPEC.md §5.1).
  • Self-describing over MCP: server-level Instructions, discoverable sandbox://guidance/* playbooks (resources) and enriched tool descriptions teach a model-host how to use the server directly over the protocol — no standalone skill file or AGENTS.md pointer needed (see below).
  • Per-command timeout: sandbox_exec accepts an optional timeout (in seconds); it is applied as a context.WithTimeout cancellation that reaches both the Docker API calls and the streaming progress channel (timeout == 0 means no deadline, SPEC.md §6.10).
  • Human-in-the-loop confirmation for destructive tools (client-side, see below).

Quick start

A minimal end-to-end path, from a fresh clone to a go test run inside a sandboxed container:

  1. Build or install the server.

    # build from source (produces binaries in dist/):
    git clone https://github.com/teran/mcp-sandbox.git && cd mcp-sandbox
    make build
    # …or install the latest release binary:
    #   go install github.com/teran/mcp-sandbox@latest
    

    Prebuilt binaries are also published on GitHub tags (goreleaser).

  2. Author a profile. Copy the bundled Go toolchain profile into the profiles directory and fill in the <PLACEHOLDER> values:

    mkdir -p ~/.config/sandbox/profiles
    cp examples/profiles/golang.yml ~/.config/sandbox/profiles/golang.yml
    # edit golang.yml: replace the <GIT_NAME>/<GIT_EMAIL> placeholders inside
    # the GIT_AUTHOR_* / GIT_COMMITTER_* env keys and the <HOST_*> mount paths
    

    Profiles are operator-authored, read-only YAML — see Profiles.

  3. Scope the host and start the server.

    export ALLOW_DIRS="/path/to/your/project"   # gates cwd + every mount source
    ./dist/mcp-sandbox
    
  4. Wire it up in opencode — deny the host shell tool and register mcp-sandbox as a local MCP server (see OpenCode setup).

  5. Create a sandbox and run a test inside it.

    sandbox_create { profile: "golang", session_id: "<opencode session id>", cwd: "/path/to/your/project" }
    sandbox_exec   { id: "<returned session id>", command: "go test ./..." }
    
  6. Clean up explicitly — there is no automatic GC:

    sandbox_destroy { id: "<returned session id>" }   # or sandbox_destroy_all
    

ℹ️ Note — cleanup is explicit, there is no automatic GC. A sandbox lives until you call sandbox_destroy / sandbox_destroy_all. Full mechanics in Sandbox lifecycle; every tool in Tool surface.

Security model

mcp-sandbox is built around a deny-by-default security model with full shell capability inside the sandbox:

  • The model-host gets full permission to run shell commands — but inside an isolated, ephemeral Docker container, never on the host.
  • What is not explicitly allowed is, by default, not available. Access is granted explicitly: host directories only via ALLOW_DIRS, network comes from the operator profile (bridge/none default, host only if the operator authors it), root inside is a scoped opt-in per SudoPolicy, package install is opt-in via provisioned images.
  • The container is hardened (read-only rootfs, drop-all capabilities, no-new-privileges, seccomp, non-root user, resource limits) and cannot be weakened by a caller (immutable Isolation).
  • Everything is ephemeral and per-session. Cleanup is explicit: a sandbox is destroyed only by sandbox_destroy / sandbox_destroy_all — there is no automatic GC (see Sandbox lifecycle).

The practical effect: the model can run any command it needs, safely confined — so the model-host no longer needs a host shell at all.

Architecture & design

Full architecture, security model, tool surface and conformance are documented in SPEC.md. Agent working conventions are in AGENTS.md.

Highlights:

  • DDD / Clean architecture with top-level packages (cmd/mcp-sandbox/, domain/, application/, infrastructure/) — no internal/.
  • Role-based backend interfaces (Backend, Lifecycle, Executable, Introspectable) with capability dispatch via type-assertion and ErrCapabilityNotSupported — no stubs.
  • Constructor-register backend factory; Docker registers in init() and is selected lazily on the first create (no outbound calls at startup).
  • Declarative tool framework: each tool is a ToolDef with annotations, instructions, input/output schema and a redaction contract, wrapped by a shared handler pipeline (validate → access-log → dispatch → redact → structured output).
  • Session lifecycle: create → use → destroy, immutable mounts. Cleanup is explicit only — see Sandbox lifecycle; there is no automatic GC.
Driver architecture

Status: implemented (in-process driver registry; profile envelope apiVersion + spec). The profile schema now prefers the envelope form apiVersion + spec (SPEC.md §7.11) — spec is the driver-owned blob that replaces the legacy opaque options:; the legacy driver: + options: + top-level cwd/shell form still works but is deprecated (Phase A is additive; see the envelope migration). The docker / seatbelt builders are registered in-process in a driver registry (domain/sandbox/driver), with the immutable hardening re-asserted by EnforceHardening at the Service level (SPEC.md §6.11, §7.11).

Delivery roadmap:

  • Phase 1 = in-process Go plugins (the implemented part).
  • Phase 2 (later, future work) = out-of-process IPC (STDIO child + protobuf-like) plus the SANDBOX_DRIVERS_DIR loader — opening other languages (not implemented).
flowchart LR
  C[sandbox_create profile=name]
  P[profile apiVersion + spec]
  R[driver registry: docker or seatbelt]
  S[SandboxSpec]
  H[EnforceHardening + ALLOW_DIRS gate]
  B[backend: container or sandbox-exec]
  C --> P --> R --> S --> H --> B

A driver is a single-sandbox primitive — it implements working with one sandbox (Create / Destroy / Exec / Info / Stats / Available), mapping onto the existing role interfaces (SPEC.md §6.2). List is not a single-sandbox primitive — it is an optional reconciliation seam; Delete is renamed Destroy. All orchestration of many sandboxes (session manager, routing, lifecycle, HITL, streaming/redaction, sandbox_list) is the server's job.

The implemented design is a driver registry + opaque driver-owned config so new drivers can be added without a commit to mcp-sandbox and without linking proprietary code into the binary. The driver-owned config is now carried in the profile envelope spec (apiVersion + spec, §7.11), which replaces the earlier options: blob (itself the Phase-7 migration target of the typed docker: / seatbelt: blocks — one-shot breaking change — see the migration guide). Built-in names (docker, seatbelt) are reserved and cannot be shadowed (duplicate registration fails closed); a driver spec that fails validation is rejected, not patched; an unknown driver fails closed at use time with ErrUnknownDriver. The core keeps a uniform data-plane security floor: after a builder produces the spec the Service re-asserts the immutable Isolation hardening (EnforceHardening) and gates every mount source by ALLOW_DIRS (S04). For external non-auditable drivers (Phase 2, future) that floor is data-plane only — the mechanism-plane is self-attested and unaudited, so a driver must fill a closed enum of isolation guarantees with a pessimistic default (missing = "not guaranteed"), and a declared weakness yields an honest REDUCED-POSTURE marker (never silently ignored, never presented as full isolation). See SPEC.md §6.11 for the full security model, the IPC/loader requirements and the testability seams.

Requirements

  • Go 1.27.3+
  • A Docker daemon (see Security note on socket access). On macOS, sandboxing can alternatively use the sandbox-exec (Seatbelt) backend without Docker — see macOS driver (SPEC.md §7.12).

Supported platforms

Releases are published for Linux and macOS — the two platforms we verify against our existing drivers: the Docker backend on Linux and the sandbox-exec (Seatbelt) backend on macOS (see the macOS driver).

Windows is untested — we do not use Windows directly and so cannot vouch for it. That said, there are currently no known limitations that would prevent mcp-sandbox from working under WSL2.

Installation

git clone https://github.com/teran/mcp-sandbox.git
cd mcp-sandbox
make build            # produces binaries in dist/

Binary releases are published on GitHub tags (goreleaser).

Configuration

The server is configured via environment variables (Local / stdio server — auth via environment, no HTTP headers).

Env Default Description
ALLOW_DIRS [] (none) Permitted host dirs for mounts — gates the session cwd and every profile mount source; empty ⇒ deny all. Still required (§7.2).
ALLOW_SYMLINKS false Allow following symlinks outside ALLOW_DIRS (unsafe, default off). Identity-only EvalSymlinks + open-then-verify, no resolved-path re-gate (§7.2).
DOCKER_HOST unix:///var/run/docker.sock Docker daemon socket (unix).
LOG_LEVEL (unset ⇒ logging disabled) Enable + level. stdio logging is on only when set.
LOG_FILENAME — stdio log file path, chmod 600.
LOG_FORMAT text text or json.
SANDBOX_IDLE_TIMEOUT 15m Accepted for compatibility but has no effect — cleanup is explicit only, there is no idle reaper.
SANDBOX_PROFILES_DIR ~/.config/sandbox/profiles Operator-authored, read-only YAML profiles — one <name>.yml each (§7.11); source of image/env/mounts/network/cgroups/user/sudo.

Removed in Phase 7: SANDBOX_CWD_MODE (→ profile cwd.mode), SANDBOX_CGROUP_CPU_LIMIT_CORES / SANDBOX_CGROUP_MEMORY_LIMIT_GB (→ profile cgroups), and TRUSTED_REGISTRIES (→ image comes from the profile; digest-pinning is the recommended convention, SPEC.md §7.9).

Example:

export ALLOW_DIRS="/Users/me/projects/myapp"
export LOG_LEVEL=info
export LOG_FILENAME=/tmp/mcp-sandbox.log
./mcp-sandbox

Access log (L08): every tools/call is logged at info with tool, redacted args, source, duration, outcome and request_id. For sandbox_exec only, the redacted command/summary are hoisted to top-level fields and the whole args map is omitted (so the per-exec env is no longer logged for that tool); every other tool logs the args map unchanged. See SPEC.md §9.

Profiles (operator-authored)

Sandboxes are created from operator-authored, read-only YAML profiles — one <name>.yml per profile under SANDBOX_PROFILES_DIR (default ~/.config/sandbox/profiles). Profiles are read on demand — the server scans SANDBOX_PROFILES_DIR on each profile lookup, so editing a <name>.yml takes effect immediately without restarting the server. A profile fully determines the sandbox runtime: image, env, mounts, network, cgroup limits, user and sudo. There are no profile create/update/delete tools; the model references a profile by name on sandbox_create, and profile_list enumerates what's available.

Example ~/.config/sandbox/profiles/default.yml (envelope form):

apiVersion: docker.profiles.sandbox.teran.dev/v1 # REQUIRED envelope; the driver is the first label of the group, vN = profile-schema version (NOT the driver implementation version)
name: default
description: the default profile
spec:          # driver-owned; replaces the legacy options: — interpreted ONLY by the selected driver's builder
  image: alpine@sha256:0000000000000000000000000000000000000000000000000000000000000000 # digest-pinning recommended — replace with the real <repo>@sha256:<64 hex>
  env:
    FOO: bar
  mounts:
    - source: /data
      target: /data
      read_only: true
  network:
    mode: bridge # bridge (default) | none | host
  cgroups:
    cpu_cores: 1 # human-readable: whole/virtual cores (1.0 = one core); raw nano_cpus takes precedence
    memory_gb: 1 # human-readable: whole GiB (swap disabled ⇒ memory_swap = memory); raw memory takes precedence
    pids_limit: 256
    ulimits:
      - name: nofile
        soft: 1024
        hard: 1024
  user:
    uid: 1000
    gid: 1000
  sudo: never
  cwd:
    target: "" # empty ⇒ mounted 1:1 at the same absolute path (default)
    mode: ro # ro (default) | rw
  shell: bash

The example above is a minimal schema illustration. For a complete, real-world profile, see examples/profiles/golang.yml — copy it into SANDBOX_PROFILES_DIR as golang.yml and fill in the <PLACEHOLDER> values (git identity, host paths). It defaults Go's build caches (GOCACHE/GOTMPDIR/GOMODCACHE) so go build/go test work out of the box inside the sandbox.

  • ALLOW_DIRS still gates every host path — both the session cwd and every profile mounts.source must be inside it (§7.2).
  • profile_list returns only name/description — env, mounts, image, user and sudo are never exposed (S02).
  • Full schema and trust model: SPEC.md §7.11.

Schema (implemented, Phase A — additive): the preferred profile form is the envelope apiVersion + spec. apiVersion is «<driver>.profiles.sandbox.teran.dev/vN» — the driver is the first DNS label of the group, and vN is the profile-schema version (NOT the driver implementation version). spec is driver-owned and replaces the legacy options:; cwd and shell live inside spec as common fields the server extracts into Profile.Cwd/Profile.Shell and removes from the driver-owned blob. The legacy driver: + options: + top-level cwd/shell form still works but is deprecated (a warning is logged at the tool boundary). Phase A is additive; making spec the only accepted form is future Phase B (owner decision). See the envelope migration, Migration to driver + options:, Driver architecture and SPEC.md §7.11.

Migrating from an older schema? See Migrations & compatibility.

Transport, auth & TLS notes
  • Transport: STDIO only. The server is spawned as a local child process by the model-host; it opens no network listener.
  • Auth: environment variables only. No OAuth2 — there is no upstream HTTP API to authorize against (see SPEC.md §3.3).
  • TLS: never implemented in-server (S01). The server has no HTTP listener, so there is no in-server TLS surface. If the server is ever placed behind a network-facing gateway, TLS termination is the reverse proxy's job.

Sandbox lifecycle

Sandboxes follow create → use → destroy:

flowchart LR
  C[sandbox_create] --> S[per-session container / session]
  S --> E[sandbox_exec + read tools]
  E --> D[sandbox_destroy / sandbox_destroy_all]
  D --> X[cleanup explicit — no automatic GC]
  • sandbox_create provisions a per-session container.
  • sandbox_exec and the read tools operate on it.
  • sandbox_destroy destroys one sandbox; sandbox_destroy_all destroys every sandbox.

Cleanup is explicit only — there is no automatic GC. A sandbox is removed only when the model-host calls sandbox_destroy / sandbox_destroy_all; otherwise it persists until then.

macOS driver (sandbox-exec backend)

An alternative backend that isolates commands with Apple's seatbelt sandbox via the /usr/bin/sandbox-exec external binary, without Docker. It is a pure-Go implementation (no cgo) that spawns sandbox-exec as a child process, applying a deny-by-default SBPL profile. See SPEC.md §7.12.

Status: implemented (portable core + darwin log stream tailer); real-macOS verification via the darwin e2e. The Docker backend remains the default. The darwin backend lives in infrastructure/backend/darwin (portable core + build-tag os/exec runner + policy-denial detection + the macOS-specific unified-log log stream tailer wrapper behind the darwin build tag), wired via the seatbelt driver (registered in the driver registry), spec.DriverSeatbelt and the SBPL generator (domain/sandbox/sbpl). Its logic is covered by unit tests (mock runner/tailer, coverage ≥ 95%) on any GOOS. Real-macOS verification — a live /usr/bin/sandbox-exec spawn and its exit-code / IsPolicyDenial signals (which cannot run inside a Docker/CI sandbox) — is exercised by the darwin e2e smoke tests (//go:build e2e && darwin) under make e2e on a dedicated macOS CI e2e job (see Development). The unified-log log stream tailer is not exercised by the e2e — it is covered by darwin-tagged unit tests only, not a live log stream (see SPEC.md §7.12).

⚠️ Warning — darwin exec: the operator tail must grant exec. The server-rendered SBPL baseline is deny-default and does NOT emit process-exec* — sbpl.Generate emits imports → (deny default) → network → mach → sysctl → file → the operator seatbelt.sbpl (last, verbatim), but no process-exec*. Without it, sandbox-exec fails at execvp() of the shell. To actually run a command, the operator-authored seatbelt.sbpl in the darwin profile must grant exec — either with (allow process-exec*) (plus the file-read/mach/sysctl allowances the shell and its runtime need — /bin, /usr/bin, /usr/lib, dyld), or with (allow default) for non-file operations plus a narrowed file scope. Both forms work. A working, verified file-deny-all profile is bundled at examples/profiles/seatbelt.yml (validated live against a real macOS host) — see the SBPL guide below. The darwin e2e drives sandbox-exec with an (allow default) SBPL directly, so it does not validate exec under the server-generated baseline (see SPEC.md §7.12).

What it is

Unlike the Docker backend — which provisions a per-session container and executes inside it — the sandbox-exec driver has no container, no daemon and no image:

  • A session is an in-memory record (the SBPL profile + env + cwd) held by the session manager; sandbox_create stores state in-process only.
  • Every sandbox_exec spawns a fresh sandbox-exec child process (os/exec, CGO_ENABLED=0) running <shell> -c <command> under the profile rules. There is no persistent container to enter.
  • sandbox_destroy / sandbox_destroy_all tear down the whole process group of live child processes gracefully: a group-wide SIGTERM lets children flush/clean up, then escalates to group-wide SIGKILL after a short, configurable grace (default 1s, hard-capped at 5s) — see SPEC.md §7.12 — and drop the in-memory session. The grace does not weaken containment (still sandboxed under SIGTERM; termination guaranteed by untrappable SIGKILL) and is bounded so a hostile SIGTERM-ignoring child cannot delay teardown unboundedly.

When to use it

  • You are on macOS and want sandboxing without running a Docker daemon (or a rootless one).
  • Commands need only file/network restrictions at the process level — not full container isolation (no separate mount/net namespaces, no cgroups).
  • CI/runners where a Docker daemon is unavailable but the host is macOS.

Prerequisites

  • macOS with /usr/bin/sandbox-exec present (default on modern macOS).
  • No root required — the sandboxed process runs under the invoking user's credentials, confined by the seatbelt profile. The server refuses to run at uid 0.

Differences from the Docker backend

Aspect Docker backend sandbox-exec backend
Isolation container (namespaces, cgroups, read-only rootfs, seccomp) seatbelt/MAC profile on a plain process (policy-based)
Runtime image + mounts + tmpfs /run,/tmp SBPL profile rules; cwd/ALLOW_DIRS as (allow|deny file-*) rules
Session provisioned container in-memory record (SBPL + env + cwd)
Exec exec into existing container new sandbox-exec child per call
Cleanup explicit destroy; AutoRemove explicit destroy; kill children on destroy/timeout
sandbox_stats cgroup resource usage not supported (no cgroups) → ErrCapabilityNotSupported
Resource limits cgroup quotas soft setrlimit only (Memory/NanoCPUs/PidsLimit not mappable)
Root inside scoped exec -u 0 subject to seatbelt policy / current user
Portability Linux/macOS (with daemon) macOS only

Example configuration

export ALLOW_DIRS="/Users/me/projects/myapp"
export LOG_LEVEL=info
./mcp-sandbox

The backend is chosen lazily on the first sandbox_create (no outbound calls at startup): on macOS with /usr/bin/sandbox-exec present the sandbox-exec backend is selected; on Linux it is unavailable and the Docker backend (or an error) is used instead.

ℹ️ Note — multi-backend. The server is not limited to one backend per process. It keeps a separate runtime (backend + session manager) per concrete driver and routes each session to the backend that owns it, so a single mcp-sandbox process can hold docker and seatbelt sandboxes simultaneously (SPEC.md §6.3). The driver itself always comes from the profile — required (the envelope apiVersion group, or the legacy driver: token); auto/empty was removed for stored profiles, and an internal auto-resolve exists only for built-in compatibility.

ℹ️ Note — portability. The sandbox-exec backend is macOS-only. On Linux there is no sandbox-exec; to sandbox there, use the Docker backend or a Linux seatbelt equivalent such as bubblewrap (bwrap). Backends are non-interchangeable isolation mechanisms, not a portable abstraction layer.

⚠️ Warning — lifecycle & leaks (documented contract). Cleanup is explicit only — there is no automatic GC. If the server process exits without an explicit sandbox_destroy, any in-flight sandbox-exec child processes may be left running. A destroy while an exec is active must signal the child before dropping the session.

Writing a Seatbelt (SBPL) profile

The darwin backend runs commands under Apple's Seatbelt sandbox, whose rules are expressed in SBPL. The server renders the profile automatically from the typed SandboxSpec; the operator supplies the permissive tail via the profile's spec.sbpl (under apiVersion: seatbelt.profiles.sandbox.teran.dev/v1 — the legacy options.sbpl under driver: seatbelt also still works, see Profiles). A working, verified example lives at examples/profiles/seatbelt.yml — a file-deny-all profile validated live against a real macOS host.

The darwin profile's spec: blob also accepts an optional env: map of session environment variables, mirroring the Docker profile's spec.env: (SPEC §7.12). As with Docker profile env, the values are collected into the redaction set and masked from output and logs (S02) — do not put secrets here. Note: the seatbelt backend delivers no file secrets — unlike Docker there is no tmpfs /run/sandbox; secrets never leave the server process as files, only redaction is applied (SPEC §7.12).

Generation order. sbpl.Generate emits sections in a fixed order — imports → (deny default) → network → mach → sysctl → file → your seatbelt.sbpl last, verbatim. Because the last matching rule wins in Seatbelt, the operator tail is where you selectively re-open surfaces the server baseline closed. In detail:

  1. (import "system.sb"), then (deny default) — the deny-everything baseline.
  2. Network: (deny network*) for none (default); (allow network-outbound) for bridge/host.
  3. Mach: (deny mach-lookup) plus an (allow mach-lookup (global-name …)) per mach_lookups entry.
  4. Sysctl: (deny sysctl*) plus an (allow sysctl-read …) per sysctls entry.
  5. File: (allow file-read* …) for every mount source / working dir inside ALLOW_DIRS (or the scratch dir); (allow file-write* …) only for read-write mounts, a cwd.mode=rw working dir and the scratch dir. Paths outside ALLOW_DIRS are silently skipped — deny-by-default (S04).
  6. Your operator seatbelt.sbpl, appended last and verbatim.

Minimal recipe to actually run a command. The server baseline does not emit (allow process-exec*), so sandbox-exec fails at execvp() of the shell unless the operator tail grants exec. Either form works:

  • (allow process-exec*) plus the file/mach/sysctl grants the shell and dyld need; or
  • (allow default) for non-file operations (process/mach/syscall/iokit/ipc) and narrow the file surface with explicit (deny file-read*) / (deny file-write*) + allow-lists — the model used by the working examples/profiles/seatbelt.yml.

In both cases remember:

  • shell must be an absolute path (/bin/bash) — sandbox-exec runs execvp(shell) against the server process PATH, not the per-exec env.
  • The dyld chain must be readable: keep /usr/lib, /System/Library, /usr/bin, /bin in file-read scope — macOS cannot start any binary without it.
  • Grant (allow file-read-metadata) globally: it exposes only stat/readlink (never contents) and lets go, golangci-lint, make, git resolve path components without whitelisting every directory.
  • Add (allow network-outbound) only if the command needs the network (curl/git fetch).

Debugging denials. (debug deny) does not work on macOS 26 — the debug macro is absent from system.sb (SBPL v3), so it fails with unbound variable: debug. Diagnose instead with: log stream --predicate 'subsystem == "com.apple.sandbox"'.

⚠️ Warning — (allow default) weakens the boundary — know the trade-off. In the file-deny-all model, (allow default) is required for non-file operations (the shell needs dozens of them and cannot start under a hand-listed deny-all), but it re-opens mach-lookup, sysctl, iokit, IPC, network and syscall. Because your seatbelt.sbpl is appended last, it overrides the server's (deny default), (deny network*), (deny mach-lookup) and (deny sysctl*). What actually isolates the example is the file scope — and (allow network-outbound) cannot be restricted by destination on macOS, so a compromised process could exfiltrate or reach internal services. Treat this backend as a file/network confinement convenience, never as container isolation (see the security posture below).

OpenCode setup

Use mcp-sandbox as the execution environment for opencode instead of the host shell.

1. Disable the host shell

In your opencode config (opencode.jsonc), deny the built-in shell tool:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [{ "action": "shell", "resource": "*", "effect": "deny" }],
}

This removes the host bash/shell tool; the model then uses the sandbox MCP for command execution.

2. Register the mcp-sandbox MCP server

mcp-sandbox is a Local / stdio server, so register it as a local MCP server:

{
  "mcp": {
    "servers": {
      "mcp-sandbox": {
        "type": "local",
        "command": ["mcp-sandbox"],
        "environment": {
          "ALLOW_DIRS": "{env:PWD}",
          "LOG_LEVEL": "info",
        },
      },
    },
  },
}
  • command launches the mcp-sandbox binary (put it on PATH or use an absolute path).
  • ALLOW_DIRS scopes which host directories the sandbox may reach; it gates the session working directory (mounted 1:1 at the same absolute path) and every profile mount source (see SPEC.md §7.2).
  • opencode passes its session id as a required session_id parameter to sandbox_create; the server records it as an opencode_session container label so each sandbox is traceable to the OpenCode session that created it. The sandbox's own id returned by sandbox_create is a namespaced session id slug:internalID (SPEC.md §7.8): docker:<container id> for the Docker backend (so a sandbox is directly traceable via docker ps) and seatbelt:<25 base36 chars> for the darwin backend — a deterministic, name-based UUIDv5 of the sandbox's identity ([profile, session_id, cwd] joined with /) so the same identity always yields the same id and ids never collide across processes. sandbox_create also takes a required profile name (from SANDBOX_PROFILES_DIR) and required cwd. The session cwd is mounted 1:1 read-only by default (see SPEC.md §7.2, §7.11).
  • Breaking id schema (v0.9+): sandbox session ids changed from a bare backend id to a namespaced slug:internalID pair. The id every tool returns/accepts now carries a docker: / seatbelt: prefix; a bare (non-namespaced) or unknown-slug id is rejected (ErrSessionNotFound) on all ops, and sandbox_destroy by an unknown slug is an error, not a no-op. Clients that persisted or echoed old bare ids must re-resolve them from a fresh sandbox_create/sandbox_list. The short display id keeps the slug (docker:deadbeef1234).
  • Use opencode mcp list / /mcps to check the server is connected.

⚠️ Warning — HITL note. Because mcp-sandbox is Local/stdio (no HTTP UI), destructive tools (sandbox_destroy, sandbox_destroy_all) require confirmation client-side by the operator — see SPEC.md §4.4.

Tool surface

Grouped read → write → delete (S03):

Tool Class Purpose Required params
sandbox_list read List sandboxes —
sandbox_info read Sandbox details id
sandbox_stats read Resource usage (docker); ErrCapabilityNotSupported on darwin id
profile_list read List operator profiles (name/description, no leakage) —
sandbox_create write Create a sandbox from an operator profile profile, session_id, cwd
sandbox_exec write Run a command inside a sandbox id, command
sandbox_destroy delete Destroy one sandbox (HITL) id
sandbox_destroy_all delete Destroy every sandbox (HITL) —

Nuances that don't fit the table:

  • sandbox_create: optional secrets (tmpfs 0600 files); the session cwd is mounted 1:1, read-only by default per the profile's cwd.mode.
  • sandbox_exec: command is a scalar string run via the profile-configured shell as a fixed [<shell>,"-c",command] wrapper — no shell-string concatenation (S11). Optional env (map[string]string, literal, no shell evaluation), summary (a presentational label, not executed), working_dir, timeout (seconds, context.WithTimeout, §6.10) and user. Output is ANSI-sanitized, the command is redacted, and live output streams via notifications/progress when a progress token is passed (§5.1).

ℹ️ Note — files come from the image, the host, or the runtime — never via MCP file-write tools. The session cwd is mounted 1:1, so the model-host writes files on the host and the container reads/executes them at the same path; runtime artifacts live in the writable tmpfs /tmp (executable where the daemon honours exec; on daemons that force noexec — e.g. Docker Desktop — compilation goes into the writable bind-mounted cwd per the profile's cwd.mode). There are no sandbox_read_file / sandbox_write_file / sandbox_copy_in / sandbox_copy_out / sandbox_install_package tools — mount + exec is the core mechanism (SPEC.md §4.2, §7.2).

All tools are openWorldHint: false and carry per-tool annotations + instructions (SPEC.md §4).

⚠️ Warning — HITL for destructive tools. Because this is a Local / stdio-only server with no HTTP UI (S12), destructive confirmation is implemented client-side — the model-host (opencode) obtains human confirmation before invoking sandbox_destroy / sandbox_destroy_all.

Self-describing MCP server

mcp-sandbox is self-describing over the MCP protocol: a model-host client can discover everything it needs without any external file (SPEC.md §5.2).

  • Server-level Instructions — a short paragraph carrying the redirect invariant ("The host shell is restricted — route commands through this sandbox server."), tool grouping (read → write → delete), a secrets warning (never put secrets in a command or env — use tmpfs 0600 secret files on sandbox_create), and an index of the guidance resources.
  • resources capability — six read-only markdown playbooks are registered under sandbox://guidance/* and appear in the MCP catalog: overview, shell-restricted-redirect, sandbox-create, sandbox-exec, filesystem-mounts (incl. the GOCACHE/GOTMPDIR recipe for compile-in- sandbox), and security. This is the only use of resources — file I/O still never goes through MCP resources (files come from the image, the host, or the runtime via mount + exec).
  • Enriched tool descriptions — sandbox_create / sandbox_exec carry a redirect note and a pointer to the relevant guidance resource, directing the model away from the host shell exactly where those tools are invoked.

There is no standalone skill file and no AGENTS.md pointer — the self-description travels with the server over the protocol, so it stays in sync with the implementation automatically.

Security

The sandbox replaces the host shell, so security is enforced by the server and cannot be weakened by a caller (SandboxSpec.Isolation is immutable):

  • Read-only rootfs; drop-all capabilities (minimal re-add); no-new- privileges; seccomp (default MVP profile; custom profile is mandatory roadmap); non-root user inside.
  • Bounded PidsLimit, Memory/MemorySwap, NanoCPUs, Ulimits (from the profile's cgroups, §7.11).
  • Network comes from the operator profile — bridge (default) or none; host is permitted only when the operator authors it into a profile, never implicitly.
  • tmpfs mounts: /run (rw,noexec,nosuid,nodev, sandbox-user-owned, holds the /run/sandbox secrets dir) and /tmp (rw,nosuid,nodev, writable; some daemons like Docker Desktop force noexec on tmpfs, so runtime compilation uses the writable bind-mounted cwd); AutoRemove=true.
  • Host filesystem access only via ALLOW_DIRS, read-only by default, canonicalized with EvalSymlinks + identity-only open-then-verify (TOCTOU); this gates the session cwd and every profile mount source; the session cwd is the sanctioned bind-mount (read-only default).
  • Single redaction layer hides secret:true fields from all output and logs; secrets delivered as tmpfs 0600 files under /run/sandbox, never command-line/image.
  • command is intentionally NOT masked in the access-log (S02 disclaimer): the sandbox_exec access-log records command as passed, not secret- redacted — no masking is applied. command is not a channel for secrets; use tmpfs 0600 secret files instead (§7.3).
  • No shell-string concatenation/interpolation (S11/N21): sandbox_exec takes a scalar command passed as one element of a fixed [<shell>,"-c",command] wrapper (shell from the profile, default bash, §7.11) — no user string is interpolated into a shell string; the only other sh -c is the server-authored fixed secret-writer script.
  • Session ids are namespaced slug:internalID (§7.8), not server-generated opaque ids: the session manager calls the backend first and uses its returned id as the internal part — for the Docker backend that is the container id (a sandbox is directly traceable to its container via docker ps), for darwin it is a deterministic, name-based 25-char derived id (a UUIDv5 of [profile, session_id, cwd], base36-encoded). An opaque crypto/rand 64-hex id is only a fallback when a backend returns an empty id. Ownership is also labelled on the container (dev.teran.sandbox.owner / the OpenCode session label).
  • Operator-authored profiles (Phase 7): the image, env, mounts, network, limits, user and sudo are declared in read-only YAML files the model references by name; a profile can never weaken the immutable Isolation block (§7.11).
  • Supply chain: sandbox images come from the operator profile with parse-only validation; digest-pinning is the recommended operator convention (§7.9), and dependencies are pinned to latest stable, signed packages.
Docker socket access (known limitation)

The Docker socket (/var/run/docker.sock) is effectively root on the host. The server mitigates this by preferring a rootless Docker daemon or running in an isolated environment with socket access confined to the server process. Review and choose the socket access model appropriate to your host. See SPEC.md §7.6.

macOS driver (security posture)

The sandbox-exec backend (SPEC.md §7.12) is policy-based containment, not kernel/container isolation and is strictly weaker than the Docker backend:

  • Shared host kernel — no namespaces; an SBPL bypass or kernel bug is a full host compromise at the operator's privilege, not a root boundary.
  • No cgroup resource quotas — only soft per-process setrlimit (nofile/cpu/as/nproc/fsize/stack/core); a runaway process can degrade the whole host (DoS). sandbox_stats → ErrCapabilityNotSupported.
  • No network isolation — macOS has no network namespaces, so only network-outbound is enforceable and it cannot be restricted by destination.
  • No uid change — the sandbox runs as the current host user (UIDGID is not applied; only euid != 0 is refused), sharing the host user's identity.
  • No no-new-privileges / read-only-rootfs / cap-drop / tmpfs-workdir enforcement — those immutable Isolation fields are validated by spec.Validate, but the darwin backend has no mechanism to enforce them (runner_darwin.go applies only Setpgid). See SPEC.md §7.12.
  • No image / digest supply-chain boundary — there is no image; SBPL runs on host libraries against the operator-authored profile.
  • Deprecated Apple API — /usr/bin/sandbox-exec(1) and sandbox_init(3) are deprecated and not guaranteed by Apple as a security boundary.
  • (allow default) boundary reduction — where the operator profile uses (allow default) for non-file operations, it re-opens mach-lookup/sysctl/ iokit/ipc/network/syscall; the real isolation is then the file scope only.

It blocks direct access to disallowed paths (e.g. cat ~/.secret) at the kernel level via a deny-by-default SBPL profile, with SBPL-injection validation on every typed path (each path is rejected if it contains any SBPL metacharacter). It is a convenience for macOS hosts — treat it as a lower-security alternative to the Docker backend, never as an equivalent. Full threat model: SPEC.md §7.13.

Migrations & compatibility

Schema has evolved through several forms; the sections below document each legacy form and how to convert to the current one. New profiles should use the envelope form (apiVersion + spec).

Migration to driver + options:

Superseded — legacy, deprecated (Phase A is additive). The driver: + options: form described in this subsection is the Phase-7 legacy form and now still works but is deprecated in favor of the envelope apiVersion + spec. New profiles should use the envelope form (see Migration to the envelope form). This subsection documents the earlier (completed) Phase-7 migration from the typed docker: / seatbelt: blocks.

The move from the typed docker: / seatbelt: blocks to the (now-deprecated Phase-A legacy) driver: + options: form was a one-shot breaking schema change (no compat shim): driver is required and auto/empty is removed, and every typed block key moves under options:. The migration is done — the old docker: / seatbelt: blocks are no longer read by the server, so any still-typed profile must be converted to the current form. Canonical converted examples are bundled at examples/profiles/golang.yml (docker) and examples/profiles/seatbelt.yml (seatbelt) — both now use the envelope form (apiVersion + spec:).

Key mapping — docker: block → options::

Old docker: key New options: key Notes
docker.image options.image Required; parse-only reference validation; digest-pinning recommended.
docker.env options.env map[string]string, redacted (S02).
docker.mounts[] options.mounts[] {source,target,read_only}; every source gated by ALLOW_DIRS.
docker.network.mode options.network.mode bridge(default)/none/host (host only when operator-authored).
docker.cgroups.nano_cpus options.cgroups.nano_cpus Raw value; takes precedence over cpu_cores.
docker.cgroups.memory options.cgroups.memory Raw value; takes precedence over memory_gb.
docker.cgroups.memory_swap options.cgroups.memory_swap Defaults to memory when unset (swap disabled).
docker.cgroups.pids_limit options.cgroups.pids_limit
docker.cgroups.cpu_cores options.cgroups.cpu_cores Friendly unit: whole/virtual cores.
docker.cgroups.memory_gb options.cgroups.memory_gb Friendly unit: whole GiB.
docker.cgroups.ulimits options.cgroups.ulimits {name,soft,hard} list.
docker.user options.user {uid,gid}, non-root.
docker.sudo options.sudo never(default)/require.

Key mapping — seatbelt: block → options::

Old seatbelt: key New options: key Notes
seatbelt.env options.env Session environment, redacted (S02).
seatbelt.sbpl options.sbpl Operator SBPL template, appended verbatim (last-match-wins).
seatbelt.mach_lookups options.mach_lookups Extra (allow mach-lookup …) services.
seatbelt.sysctls options.sysctls Extra (allow sysctl-read …) keys.

Unknown options: keys fail closed at build time. Each built-in builder rejects an unknown top-level options: key rather than silently ignoring it — the docker builder accepts only image, env, mounts, network, cgroups, user, sudo; the seatbelt builder only sbpl, mach_lookups, sysctls, env.

Convert checklist:

  1. Read the existing docker: block (or seatbelt: block) from your profile.
  2. Set driver: docker (or driver: seatbelt) at the top level — required; there is no auto/empty form anymore.
  3. Move the block's keys under a top-level options: blob using the mapping tables above.
  4. Keep name, description, cwd, shell top-level — they are not part of options:.
  5. Restart/refresh — profiles are read on demand, so the converted file takes effect immediately on the next lookup.

Example target form:

name: default
description: the default profile
driver: docker # REQUIRED; the registry key (auto/empty removed)
options:        # opaque; interpreted ONLY by the docker driver
  image: alpine@sha256:…
  env: { FOO: bar }
  mounts:
    - source: /data
      target: /data
      read_only: true
  network: { mode: bridge }
  cgroups: { cpu_cores: 1, memory_gb: 1, pids_limit: 256 }
  user: { uid: 1000, gid: 1000 }
  sudo: never
cwd: { target: "", mode: ro }
shell: bash

The built-in driver names docker and seatbelt are reserved and cannot be shadowed by an external driver (duplicate registration fails closed); a driver spec that fails validation is rejected, not patched; an unknown driver fails closed at use time. Full schema and security model: SPEC.md §7.11/§6.11.

Migration to the envelope form (apiVersion + spec)

The preferred profile schema is the envelope apiVersion + spec (Phase A, additive — SPEC.md §7.11). The legacy driver: + options: + top-level cwd/shell form continues to work but is deprecated (a warning is logged at the tool boundary). Migration is a 1:1 mechanical rename — spec: replaces options:, the driver moves from the driver: token into the apiVersion group, and top-level cwd/shell move inside spec.

Key mapping — legacy driver + options: → envelope apiVersion + spec:

Legacy (driver + options:) New (apiVersion + spec)
driver: docker apiVersion: docker.profiles.sandbox.teran.dev/v1
driver: seatbelt apiVersion: seatbelt.profiles.sandbox.teran.dev/v1
options: (whole block) spec: (whole block)
options.image spec.image
options.env spec.env
options.mounts spec.mounts
options.network spec.network
options.cgroups spec.cgroups
options.user spec.user
options.sudo spec.sudo
top-level cwd: spec.cwd:
top-level shell: spec.shell:

The apiVersion is «<driver>.profiles.sandbox.teran.dev/vN» — the driver is the first DNS label of the group (so docker → docker.profiles.sandbox.teran.dev, seatbelt → seatbelt.profiles.sandbox.teran.dev) and vN is the profile-schema version (NOT the driver implementation version). Built-in drivers declare …/v1. On USE time the server's driver.Reconcile compares the profile's apiVersion against the driver's declared version; a mismatch fails closed with ErrAPIVersionMismatch. Legacy profiles without an apiVersion pass this check unrestricted.

Convert checklist (legacy → envelope):

  1. Read the legacy driver: value and set apiVersion: to the matching «<driver>.profiles.sandbox.teran.dev/v1» (see table).
  2. Rename the whole options: block to spec:.
  3. Move top-level cwd: and shell: inside spec:.
  4. Remove the now-redundant driver: key (the driver now comes from the apiVersion group). name and description stay at the top level.
  5. Restart/refresh — profiles are read on demand, so the converted file takes effect immediately on the next lookup.

Example conversion — legacy docker profile:

# legacy (deprecated)
name: default
description: the default profile
driver: docker
options:
  image: alpine@sha256:…
  env: { FOO: bar }
  mounts:
    - source: /data
      target: /data
      read_only: true
  network: { mode: bridge }
  cgroups: { cpu_cores: 1, memory_gb: 1, pids_limit: 256 }
  user: { uid: 1000, gid: 1000 }
  sudo: never
cwd: { target: "", mode: ro }
shell: bash
# new envelope form
apiVersion: docker.profiles.sandbox.teran.dev/v1
name: default
description: the default profile
spec:
  image: alpine@sha256:…
  env: { FOO: bar }
  mounts:
    - source: /data
      target: /data
      read_only: true
  network: { mode: bridge }
  cgroups: { cpu_cores: 1, memory_gb: 1, pids_limit: 256 }
  user: { uid: 1000, gid: 1000 }
  sudo: never
  cwd: { target: "", mode: ro }
  shell: bash

Roadmap (Phase B, future — owner decision): Phase A keeps the legacy form working. A later Phase B will make the .spec envelope the only accepted profile form and remove legacy driver:/options:/top-level cwd/shell — a breaking change scheduled by the owner, not yet done.

Migration from the old sandbox_create

sandbox_create is breaking in Phase 7: the per-request parameters image, env, mounts, nano_cpus, memory, pids_limit, uid, gid, sudo are removed and now come from a profile. profile and cwd are now both required (with session_id). To migrate:

  1. Author a profile capturing the desired image/env/mounts/limits/user/sudo in SANDBOX_PROFILES_DIR (see above).
  2. Call sandbox_create with { "profile": "default", "session_id": "...", "cwd": "...", "secrets": [...] } — no other runtime knobs.
  3. Any un-migrated caller that passes the old parameters is rejected with InvalidParams.

Terminology

A short glossary of terms used throughout this document and SPEC.md:

  • Phase 7 / Phase A / Phase B — roadmap phases for the profile schema. Phase 7 introduced operator-authored profiles; Phase A made the envelope form additive (legacy still works); a future Phase B will make spec the only accepted form.
  • Driver — a single-sandbox primitive (one sandbox: create/destroy/exec/ info/stats) selected by the profile (docker / seatbelt).
  • Envelope — the preferred profile form: apiVersion («<driver>. profiles.sandbox.teran.dev/vN») + a driver-owned spec blob.
  • options: — the legacy driver-owned profile blob, replaced by spec:.
  • ALLOW_DIRS — the server env var gating which host directories the sandbox may reach (session cwd and every profile mount source).
  • SBPL / seatbelt — Apple's Sandbox Profile Language; the rule syntax for the macOS sandbox-exec backend.
  • HITL — human-in-the-loop confirmation, required client-side for destructive tools.
  • §7.x — references into SPEC.md (e.g. §7.11 profiles, §7.12 darwin, §7.8 session ids).

Development

TDD workflow

All fixes/features are done TDD-style (T01): @qa writes tests first (isolated context), @developer writes the implementation (isolated context). Tests are never weakened to make the implementation pass.

  • Unit tests: make test — go test -race + coverage ≥ 95% gate (fails below).
  • Mutation testing: gremlins as a hard gate (80/80) — dedicated CI job.
  • e2e: scoped — a darwin e2e smoke suite exists (//go:build e2e && darwin) and runs under the generic make e2e (go test -tags e2e ./...) on a dedicated macOS CI e2e job; on Linux it is excluded by the darwin build tag (there is no e2e-darwin target by design). Docker-in-Docker e2e remains out of scope — a real Docker e2e would need a nested/rootless daemon or socket access, conflicting with the immutable sandbox hardening; the handler→backend path is covered by unit tests + the coverage gate.
Quality gates

CI (GitHub Actions) binds to the make interface (R07) and enforces: make lint (golangci-lint, gosec, govulncheck, go-arch-lint), make test (race + coverage ≥ 95%), make e2e (darwin e2e smoke on a dedicated macOS e2e job), make build (goreleaser), plus hard-gate jobs for gremlins (mutation) and gitleaks (secret scan). Findings are fixed, not suppressed. CI never mutates repository state.

License

See LICENSE.

Directories

Path Synopsis
application
config
Package config loads the env-driven server configuration (via envconfig) and validates the filesystem scope (S04).
Package config loads the env-driven server configuration (via envconfig) and validates the filesystem scope (S04).
profile
Package profile implements the application-layer, read-only profile store (Phase 7).
Package profile implements the application-layer, read-only profile store (Phase 7).
session
Package session implements the in-memory session manager (SPEC §6.6).
Package session implements the in-memory session manager (SPEC §6.6).
tools/def
Package def defines the declarative tool model (SPEC §6.4): a ToolDef is a complete, strongly-typed declaration of an MCP tool — its identity, annotations, per-tool instructions, strict input/output schemas, redaction contract and the application-layer handler that implements it.
Package def defines the declarative tool model (SPEC §6.4): a ToolDef is a complete, strongly-typed declaration of an MCP tool — its identity, annotations, per-tool instructions, strict input/output schemas, redaction contract and the application-layer handler that implements it.
tools/guidance
Package guidance provides the self-describing MCP guidance for mcp-sandbox: server-level Instructions text plus a registry of `sandbox://guidance/*` resources (overview, redirect, create, exec, filesystem-mounts, security) served to the model-host over the MCP resources protocol.
Package guidance provides the self-describing MCP guidance for mcp-sandbox: server-level Instructions text plus a registry of `sandbox://guidance/*` resources (overview, redirect, create, exec, filesystem-mounts, security) served to the model-host over the MCP resources protocol.
tools/handler
Package handler implements the shared handler-wrapper (SPEC §6.4) that every tool must pass through.
Package handler implements the shared handler-wrapper (SPEC §6.4) that every tool must pass through.
tools/profile
Package profile declares the read-only profile_list tool (Phase 7): it enumerates the operator-authored profiles by name and description only, so no env value, mount source, user identity or image leaks into output or logs (S02).
Package profile declares the read-only profile_list tool (Phase 7): it enumerates the operator-authored profiles by name and description only, so no env value, mount source, user identity or image leaks into output or logs (S02).
tools/registry
Package registry holds the declarative tool registry (SPEC §6.4).
Package registry holds the declarative tool registry (SPEC §6.4).
tools/sandbox
Package sandbox declares the concrete sandbox tool set (SPEC §4) as declarative ToolDefs and the application-layer Service interface the tools depend on.
Package sandbox declares the concrete sandbox tool set (SPEC §4) as declarative ToolDefs and the application-layer Service interface the tools depend on.
cmd
mcp-sandbox command
Command mcp-sandbox is the composition root of the mcp-sandbox MCP server (Local, stdio-only).
Command mcp-sandbox is the composition root of the mcp-sandbox MCP server (Local, stdio-only).
domain
progress
Package progress provides a small pure-domain mechanism for streaming progress notifications from long-running tools (Phase 6, SPEC §7.x / roadmap item 6.x).
Package progress provides a small pure-domain mechanism for streaming progress notifications from long-running tools (Phase 6, SPEC §7.x / roadmap item 6.x).
requestid
Package requestid provides a minimal domain-level request-id correlation mechanism (L09).
Package requestid provides a minimal domain-level request-id correlation mechanism (L09).
sandbox/driver
Package driver defines the driver-registry + opaque options model (SPEC §6.11 / §7.11).
Package driver defines the driver-registry + opaque options model (SPEC §6.11 / §7.11).
sandbox/exec
Package exec defines the typed request/result types for executing a command inside a sandbox.
Package exec defines the typed request/result types for executing a command inside a sandbox.
sandbox/profile
Package profile defines the operator-authored, read-only sandbox profile model (Phase 7, SPEC §7.11).
Package profile defines the operator-authored, read-only sandbox profile model (Phase 7, SPEC §7.11).
sandbox/role
Package role defines the ISP role interfaces that a backend implements and the capability set used to dispatch them via type-assertion (§6.2).
Package role defines the ISP role interfaces that a backend implements and the capability set used to dispatch them via type-assertion (§6.2).
sandbox/sbpl
Package sbpl renders a deterministic Seatbelt (SBPL) profile from a typed SandboxSpec for the darwin / sandbox-exec backend (SPEC §7.12).
Package sbpl renders a deterministic Seatbelt (SBPL) profile from a typed SandboxSpec for the darwin / sandbox-exec backend (SPEC §7.12).
sandbox/spec
Package spec defines the typed SandboxSpec and the immutable Isolation policy that the server enforces on every container create (§7.1).
Package spec defines the typed SandboxSpec and the immutable Isolation policy that the server enforces on every container create (§7.1).
session
Package session defines the sandbox session aggregate and the session manager interface (SPEC §6.6, §7.8).
Package session defines the sandbox session aggregate and the session manager interface (SPEC §6.6, §7.8).
infrastructure
backend
Package backend provides the constructor-register for sandbox backends and the capability-based selection logic (SPEC §6.3).
Package backend provides the constructor-register for sandbox backends and the capability-based selection logic (SPEC §6.3).
backend/darwin
Package darwin implements the sandbox backend roles on Apple macOS through the external /usr/bin/sandbox-exec (Seatbelt) binary (SPEC §7.12).
Package darwin implements the sandbox backend roles on Apple macOS through the external /usr/bin/sandbox-exec (Seatbelt) binary (SPEC §7.12).
backend/docker
Package docker implements the sandbox backend roles through the official docker SDK over the unix socket (SPEC §6.2, §7; L02GO/N05GO).
Package docker implements the sandbox backend roles through the official docker SDK over the unix socket (SPEC §6.2, §7; L02GO/N05GO).
logging
Package logging configures logrus for the server (L01–L09, L01GO–L04GO): stdio→file channel, enablement by LOG_LEVEL, banner, SDK slog→logrus wiring, access-log at info, request_id correlation and a single redaction helper driven by `secret:true` annotations (S02).
Package logging configures logrus for the server (L01–L09, L01GO–L04GO): stdio→file channel, enablement by LOG_LEVEL, banner, SDK slog→logrus wiring, access-log at info, request_id correlation and a single redaction helper driven by `secret:true` annotations (S02).
mcp
Package mcp wires the sandbox tools into an MCP server (SPEC §3, §5): it builds the go-sdk server (ServerOptions.Logger = slog→logrus, per-tool instructions), registers every ToolDef through the shared handler-wrapper, and provides the concrete sandbox Service (lazy backend selection + session manager) plus the access-log adapter over logrus.
Package mcp wires the sandbox tools into an MCP server (SPEC §3, §5): it builds the go-sdk server (ServerOptions.Logger = slog→logrus, per-tool instructions), registers every ToolDef through the shared handler-wrapper, and provides the concrete sandbox Service (lazy backend selection + session manager) plus the access-log adapter over logrus.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL