docker

type Options struct {
	// Image is the container image to run. It MUST contain everything the toolset
	// shells out to — sh (the run tool), rg (the search tool execs it directly),
	// git, and go if in-sandbox builds are expected. See ./Dockerfile. Empty =>
	// DefaultImage.
	Image string

	// Runtime selects the OCI runtime. "" (or "runc") is the standard
	// shared-kernel container => IsolationProcess. "runsc" is gVisor — syscalls
	// hit a userspace app-kernel, not the host kernel => IsolationKernel. This is
	// the one-flag gVisor graduation (docs/specs/SANDBOX.md): it threads straight into
	// `docker run --runtime=`. The host must have the runtime registered with the
	// daemon; we don't verify that here — a missing runtime surfaces as a New
	// error from the daemon.
	Runtime string

	// Network, when false (the default), runs the container with --network none:
	// no exfiltration, no callbacks, no module fetches. This is the point for
	// genuinely untrusted code — the workspace must be self-contained (see the
	// module story: ExtraMounts can carry a read-only GOMODCACHE). Set true for
	// trusted-but-isolated cases that need egress.
	Network bool

	// User is the in-container user as "uid:gid". Defaulting it to the HOST uid:gid
	// (New does this when empty) serves two purposes at once: it runs non-root in
	// the container, AND files the container writes to the bind mount are owned by
	// the host user, so host-side file ops can read them back (the uid-mismatch
	// gotcha, §13). Set explicitly to override.
	User string

	// WorkdirMount is the in-container path the workspace dir is bind-mounted to
	// and the working directory for every Exec. Empty => DefaultWorkdir
	// ("/workspace"). The mount is the ONLY writable mount; the root filesystem is
	// read-only.
	WorkdirMount string

	// Memory, PidsLimit, CPUs cap resource use to contain a fork bomb, a memory
	// bomb, or CPU spin (§6). They map to --memory, --pids-limit, --cpus. Empty/0
	// => the DefaultLimits below. A limit of "0" / NoLimit can be set explicitly to
	// disable a given cap (not recommended for untrusted code).
	Memory    string // e.g. "512m"; "" => DefaultMemory.
	PidsLimit int    // e.g. 256; 0 => DefaultPidsLimit; negative => unlimited.
	CPUs      string // e.g. "1.0"; "" => DefaultCPUs.

	// WritableRootFS drops the --read-only root filesystem. The default (false,
	// read-only) is the right posture for OUR sandbox image, where the workspace
	// mount is the only thing a task should write. Set true ONLY for prebuilt
	// third-party images whose tooling must write outside the workspace — e.g.
	// SWE-bench instance images, where the conda env under /opt/miniconda3 needs
	// .pyc/install writes for the baked-in test tooling to run. This widens the
	// blast radius from "workspace only" to "container filesystem" — the container
	// boundary (caps dropped, no-new-privileges, resource caps, --rm teardown) is
	// then the whole guarantee, and the rootfs is no longer attestable as pristine.
	WritableRootFS bool

	// ExtraMounts are additional bind mounts as raw `docker run -v` specs, e.g.
	// "/home/u/go/pkg/mod:/go/pkg/mod:ro" to give in-container `go build` a
	// read-only host module cache while --network none stays on (the module story,
	// §13). Each is passed through verbatim; the caller owns the trust decision for
	// what it mounts (mount read-only for anything outside the workspace).
	ExtraMounts []string

	// ExtraEnv are environment variables set on every Exec, each "KEY=VALUE". Use
	// for things like GOFLAGS=-mod=mod or GOPROXY=off that a network-off build
	// needs. Per-command Env (sandbox.Command.Env) is merged on top of these.
	ExtraEnv []string

	// Binary is the container CLI to invoke. Defaults to "docker"; Podman is
	// CLI-compatible, so setting "podman" works without any other change. We add no
	// Podman-specific code — this is the entire Podman story (a configurable
	// binary), per the design decision.
	Binary string

	// StartTimeout bounds `docker run` (image pull + container start). 0 =>
	// DefaultStartTimeout. A slow pull shouldn't hang New forever.
	StartTimeout time.Duration

	// MaxOutputBytes caps how much stdout (and, separately, stderr) Exec retains
	// from a command. Hostile code can flood output (`yes`, a stderr loop) to OOM
	// the agent; the runner stops STORING past this many bytes while still draining
	// the stream so the process isn't blocked. 0 => DefaultMaxOutputBytes; negative
	// => unlimited (only for trusted use). The tool layer clips again for the model
	// (agent/tools.go); this is the memory-safety bound underneath it (P4).
	MaxOutputBytes int64
}

type Sandbox struct {
	*local.Sandbox // file ops + path fence, host-side on the workspace dir (D1).
	// contains filtered or unexported fields
}