sandbox

Documentation

Overview

Package sandbox wraps agent shell commands in an OS-level containment layer — defense-in-depth UNDER the permission classifier, not a replacement for it. The classifier decides whether a command may run; the sandbox bounds what a permitted command can touch if it (or something it spawns) misbehaves.

Modes:

ReadOnly   — read-only sessions (plan/scout shells): the filesystem is
             readable but only tmp + tool caches are writable. Always on
             for read-only sessions when the platform supports it.
Workspace  — writes confined to the repo root + tmp + tool caches.
             Opt-in for normal sessions via MEMCODE_SANDBOX=1.

Backends: macOS sandbox-exec (Seatbelt), Linux bubblewrap (bwrap) when installed. No backend → commands run unwrapped, exactly as before (fail open: the sandbox strengthens an existing gate, it must never brick a platform). MEMCODE_SANDBOX=0 force-disables wrapping everywhere.

Index

• Constants
• func Supported(p Policy) bool
• func Wrap(command string, p Policy) (string, bool)
• type Mode
• type Policy
  • func PolicyFor(readOnly bool, root string) Policy

Constants

const EnvVar = "MEMCODE_SANDBOX"

EnvVar toggles sandboxing for NORMAL sessions: "1"/"true"/"workspace" wraps every bash call in Workspace mode; "0"/"off" force-disables all wrapping (including the read-only default) as the escape hatch.

Functions

func Supported

func Supported(p Policy) bool

Supported reports whether Wrap would ACTUALLY contain under p on this platform — callers that scale a permission gate to the containment (mcp_code_exec: sandboxed+no-network = Medium, unsandboxed = Dangerous) must know the difference between "asked for a sandbox" and "got one".

func Wrap

func Wrap(command string, p Policy) (string, bool)

Wrap returns a shell line that runs command under the policy's containment, and whether wrapping applies. ok=false means run the command unchanged (policy Off, or no backend on this platform).

Types

type Mode

type Mode int

Mode is the containment level.

const (
	Off Mode = iota
	ReadOnly
	Workspace
)

type Policy

type Policy struct {
	Mode Mode
	Root string // repo root (Workspace mode's writable tree)
	// DenyNetwork additionally cuts ALL network egress (Seatbelt deny network*,
	// bwrap --unshare-net). Used by mcp_code_exec: with writes confined AND no
	// network, generated code loses its exfiltration channel and can gate at
	// Medium instead of Dangerous. Bash keeps network (builds/tests need it).
	DenyNetwork bool
}

Policy is what a wrapped command may touch.

func PolicyFor

func PolicyFor(readOnly bool, root string) Policy

PolicyFor decides the policy for a bash call: read-only sessions always get ReadOnly containment; normal sessions get Workspace only when opted in.