sandbox

type Availability ¶

type Availability struct {
	// OK is true when the driver can boot a guest with a real hardware boundary on this
	// host right now.
	OK bool
	// Detail explains the verdict: what was found, or what is missing (no KVM device,
	// no hypervisor support, no runtime configured), so an operator knows what to install.
	Detail string
}

Availability reports whether a driver can run a microVM on this host, and why or why not in plain language for an operator. Detection never silently downgrades: a driver that cannot guarantee the hardware boundary reports OK=false with a reason, and the gate refuses the untrusted work rather than running it somewhere weaker.

type CaptureSpec ¶

type CaptureSpec struct {
	// Argv is the program and its arguments, executed directly without a shell. Argv[0]
	// is the binary to run; the rest are passed verbatim.
	Argv []string
	// Stdin, when non-empty, is written to the process's standard input and the stream is
	// then closed, the same off-the-command-line path Command.Stdin uses for a secret.
	Stdin []byte
	// Env grants additional KEY=VALUE variables on top of the sandbox's deny-by-default
	// baseline, the same brokered path WithEnv and StreamSpec.Env feed. A granted value
	// overrides the baseline value for the same key.
	Env []string
}

CaptureSpec is a program to run to completion under the sandbox with its combined standard output and standard error collected and returned. It is the argv counterpart of Command: Command runs a shell line (sh -c / cmd /c), while Capture runs the program directly from its Argv, never through a shell, so a path or flag cannot be reinterpreted as shell syntax. It is for a caller that must run a program directly and read all of its output, the external-agent detection probe being the first: it runs a CLI's --version/--help/status and matches on the text, some of which a CLI writes to stderr.

The deny-by-default environment applies exactly as it does to Exec, Serve, and Stream: the host environment is never inherited, so no secret the agent holds reaches the process unless Env grants it by name.

type Command ¶

type Command struct {
	// Line is the command line, interpreted by the sandbox's shell.
	Line string
	// Stdin, when non-empty, is written to the command's standard input and the stream
	// is then closed. It is the safe way to pass a secret to a command that reads one on
	// stdin (a credential import, a passphrase), because the value travels on a pipe: it
	// is never placed on the command line (argv, visible to other processes through the
	// process table) and never appears in the command's rendered text or any log. A
	// caller handling a credential builds it here rather than interpolating it into Line.
	Stdin []byte
}

Command is a shell command to run inside a sandbox.

type Contained ¶

type Contained interface {
	Containment() Containment
}

Contained is the optional capability a sandbox implements to report how strongly it isolates work. A sandbox that does not implement it is treated as the weakest level, so an unknown tier is never assumed to contain more than it proves.

type ContainerDriver ¶

type ContainerDriver interface {
	// Name identifies the engine for logs, errors, and the spine ("docker", "podman").
	Name() string
	// Detect reports whether this engine can run a container on the host right now,
	// without running one, never silently downgrading.
	Detect() Availability
	// Run starts the container for spec and returns a handle to its loopback endpoint. An
	// error means no container was started.
	Run(ctx context.Context, spec ContainerSpec) (Serving, error)
}

ContainerDriver runs a container for a spec on a specific OCI engine. A driver only executes the composed command and adopts the running container as a Serving handle; the security posture is already fixed by buildContainerArgv and the spec validation, so a driver cannot weaken it. Implementations must be safe for concurrent use.

func ContainerDrivers() []ContainerDriver

func NewContainerDriver(engine OCIEngine, runner Runner) ContainerDriver

func SelectContainerDriver() (ContainerDriver, error)

type ContainerImage ¶

type ContainerImage struct {
	// Ref is the image reference without the digest, e.g. "vllm/vllm-openai:v0.6.0". It is
	// recorded for diagnostics; the digest is what the run actually pins to.
	Ref string
	// Digest is the content digest the image is pinned to, "sha256:" followed by 64 hex
	// characters. The run uses ref@digest so a moved tag cannot substitute a different image.
	Digest string
}

ContainerImage names the image to run and the content digest it must be pinned to. A tag alone is mutable (a registry can move it), so the tier refuses an unpinned image: the digest is the trust anchor, the same discipline the binary-runtime releases use.

type ContainerSpec ¶

type ContainerSpec struct {
	// Image is the digest-pinned image to run.
	Image ContainerImage
	// Guarantees is the security composition (egress, caps, mounts, env) reused from the
	// microVM tier; it is validated the same way, so an untrusted container cannot run
	// with the network open, no memory cap, or a writable host mount.
	Guarantees Guarantees
	// GPU optionally grants the host accelerator.
	GPU GPURequest
	// Network is the name of the host-prepared, egress-controlled network a serving
	// container joins, so its only outbound path is the governed one. It is required when
	// a port is published (a published container cannot run network-isolated) and must be
	// empty otherwise, in which case the container runs with no network at all.
	Network string
	// HostPort and ContainerPort publish the container's server on a host loopback port.
	// ContainerPort 0 means the container publishes nothing and runs network-isolated.
	HostPort      int
	ContainerPort int
	// Command, when set, is the argv run inside the container, appended after the image so
	// it overrides the image's default command (the engine runs `run <opts> <image>
	// <command...>`). For a serving runtime it is the server invocation, for example the
	// vLLM serve arguments. It is argv, never a shell string, so nothing in it is
	// interpreted by a shell. Empty runs the image's own entrypoint and command.
	Command []string
	// ExecScratch makes the in-memory /tmp scratch executable. It is off by default so the
	// container's only writable area cannot also run code, the hardened posture. A runtime
	// that compiles and runs code at startup needs it on: a GPU inference server JIT-compiles
	// its kernels into the scratch directory and must execute them from there, so a noexec
	// scratch makes it fail to start. The scratch is still in-memory and per-container, and
	// the root filesystem stays read-only either way.
	ExecScratch bool
}

ContainerSpec is a request to run a container under the tier's guarantees: which image, the shared security composition, an optional GPU grant, the network it joins, and the loopback port its server is published on.

type Containment ¶

type Containment int

Containment is how strongly a sandbox tier isolates the work inside it, on an ordered scale: a higher level contains strictly more. The critical axis is the last one a level adds, the kernel/hardware exploit boundary, because the worst case for untrusted code is arbitrary execution that escapes a shared kernel.

The level is what lets the run gate decide, before anything executes, whether a tier is strong enough for the work's trust level, and refuse rather than run untrusted code somewhere it could break out.

const (
	// ContainmentNone is a process jail: the work is confined to a directory and runs
	// without the agent's environment, but shares the host kernel, network, and
	// syscalls. Suitable only for trusted code (the agent's own tools).
	ContainmentNone Containment = iota
	// ContainmentKernel adds kernel-enforced confinement of the filesystem, syscalls,
	// and namespaces (Landlock/seccomp, Seatbelt, AppContainer). Suitable for
	// semi-trusted, model-authored code; still a shared kernel.
	ContainmentKernel
	// ContainmentContainer adds a container's namespacing and resource control, but
	// still over a shared host kernel, so it is not a boundary for untrusted code.
	ContainmentContainer
	// ContainmentUserKernel re-implements syscalls in user space off the host kernel
	// (a user-space-kernel sandbox), a strong boundary with some compatibility cost.
	ContainmentUserKernel
	// ContainmentMicroVM gives the work its own kernel on hardware virtualization, so
	// a kernel exploit inside cannot reach the host. The boundary for untrusted code.
	ContainmentMicroVM
	// ContainmentRemote runs the work off this host entirely, the strongest
	// blast-radius separation.
	ContainmentRemote
)

func ContainmentOf(sb Sandbox) Containment

func Required(t Trust) Containment

func (c Containment) String() string

type Driver ¶

type Driver interface {
	// Name identifies the backend for logs, errors, and the spine (for example "kvm",
	// "hvf", "hyperv").
	Name() string
	// Detect reports whether this backend can boot a guest with a real hardware boundary
	// on this host right now, without booting one.
	Detect() Availability
	// Boot launches a guest confined to spec.Guarantees and returns it. An error means no
	// guest was created.
	Boot(ctx context.Context, spec Spec) (Machine, error)
}

Driver is a platform's hardware-virtualization backend: it detects whether the host can run a microVM and boots a confined guest. Each platform registers its driver in init under its build tag, so the core binary carries only the detection surface and a platform pulls in only its own VMM primitives.

func Drivers() []Driver

type ExecResult ¶

type ExecResult struct {
	Output   string // combined stdout and stderr
	ExitCode int
}

ExecResult is the outcome of a Command. A non-zero ExitCode is a normal result, not an error: the command ran and the caller reads its output and code. An error from Exec means the command could not be run at all.

type GPURequest ¶

type GPURequest struct {
	// Enabled exposes the GPU to the container.
	Enabled bool
	// Device, when set, scopes access to specific device ids (e.g. "0" or "0,1"). Empty
	// with Enabled exposes all GPUs.
	Device string
}

GPURequest grants a container access to the host GPU. It is off by default: a container sees no accelerator unless one is explicitly requested, and the host must have the passthrough tooling (checked by the caller against the hardware capability probe).

type Guarantees ¶

type Guarantees struct {
	// EgressDenied withholds all outbound network from the guest, so an inference
	// process cannot exfiltrate data or reach a command-and-control host. It must be
	// true for the untrusted posture; the network is denied at the virtualization
	// boundary, not merely inside the guest.
	EgressDenied bool
	// Limits caps the guest's CPU, memory, processes, and lifetime.
	Limits Limits
	// Mounts are the host paths exposed to the guest; for an untrusted guest each one
	// must be read-only.
	Mounts []Mount
	// Env is the explicit, secret-free set of variables the guest sees. The host
	// environment is never inherited, so a secret the agent holds cannot leak into the
	// guest; only what is named here is passed.
	Env map[string]string
}

Guarantees is the non-negotiable security composition every microVM workload runs under: the egress posture, the resource caps, the secret-free environment, and the read-only host mounts. The tier validates them before a guest boots and refuses a spec that would weaken the untrusted-code posture, so a caller cannot accidentally launch a guest with the network open, unbounded memory, or a writable host mount. This is the boundary's aggregation of every defense-in-depth layer in one place.

func Untrusted(lim Limits, mounts ...Mount) Guarantees

type Image ¶

type Image struct {
	// Kernel is the absolute host path to the guest kernel to boot.
	Kernel string
	// RootFS is the absolute host path to the guest root filesystem image.
	RootFS string
}

Image names the guest's kernel and root filesystem, the bytes the VMM boots. Flynn does not ship a hypervisor or a guest image; a host provisions them and names them here, so the tier stays a thin, auditable boundary over whatever virtualization the host already trusts.

type Limits ¶

type Limits struct {
	// VCPUs is the number of virtual CPUs the guest may use; a value <= 0 means a
	// single vCPU, the safe floor.
	VCPUs int
	// MemMiB is the guest's RAM ceiling in MiB. It must be > 0: a microVM with no
	// memory cap is refused.
	MemMiB int
	// PIDs caps the number of processes in the guest, bounding a fork bomb; a value
	// <= 0 applies the driver's default cap rather than leaving it unbounded.
	PIDs int
	// Wall is a hard wall-clock lifetime for the guest, after which it is torn down
	// regardless of progress; 0 leaves the lifetime to the caller's context.
	Wall time.Duration
}

Limits caps a guest's resource use, the runaway and cost breaker enforced at the virtualization boundary rather than left to the guest. A guest with no memory bound is refused: an unbounded VM is a denial-of-service surface, not a contained one.

type Local ¶

type Local struct {
	// contains filtered or unexported fields
}

Local is the in-process sandbox tier: the floor that runs everywhere with no host support required. It confines all file operations to a working-directory root (a path that escapes via "..", an absolute path, or a symlink pointing outside is denied) and runs commands in that directory. It is not strong isolation on its own - a command it runs otherwise has the host user's privileges outside the working tree. WithNetworkDenied, WithReadOnlyFS, and WithSeccomp add kernel-enforced network, filesystem, and syscall isolation where the platform supports it; the container, microVM, and remote tiers build on the same Sandbox port. Local is always present underneath them as the default-deny FS floor.

func NewLocal(dir string, opts ...LocalOption) (*Local, error)

func (l *Local) Capture(ctx context.Context, spec CaptureSpec) (ExecResult, error)

func (l *Local) Close() error

func (l *Local) ConfinementTier() string

func (l *Local) Containment() Containment

func (l *Local) Exec(ctx context.Context, cmd Command) (ExecResult, error)

func (l *Local) Glob(_ context.Context, pattern string) ([]string, error)

func (l *Local) ReadFile(_ context.Context, path string) ([]byte, error)

func (l *Local) Root() string

func (l *Local) Serve(_ context.Context, spec ServeSpec) (*Process, error)

func (l *Local) Session(ctx context.Context, spec SessionSpec) (*Session, error)

func (l *Local) Stream(ctx context.Context, spec StreamSpec) (*StreamProcess, error)

func (l *Local) Walk(_ context.Context, root string) ([]string, error)

func (l *Local) WritableDirs() []string

func (l *Local) WriteFile(_ context.Context, path string, data []byte) error

type LocalOption ¶

type LocalOption func(*Local)

LocalOption configures a Local sandbox.

func WithDefaultConfinement() LocalOption

func WithEgress(policy netguard.Policy) LocalOption

func WithEnv(vars map[string]string) LocalOption

func WithExecTimeout(d time.Duration) LocalOption

func WithHostReadable() LocalOption

func WithKernelConfinement() LocalOption

func WithLoopbackForward(hostAddr string) LocalOption

func WithNetworkDenied() LocalOption

func WithReadOnlyFS() LocalOption

func WithReadableDir(paths ...string) LocalOption

func WithResourceLimits(r ResourceLimits) LocalOption

func WithSeccomp() LocalOption

func WithWritableDir(paths ...string) LocalOption

type Machine ¶

type Machine interface {
	// Exec runs a command to completion inside the guest and returns its result. A
	// non-zero exit is a result, not an error; an error means the command could not be
	// run at all.
	Exec(ctx context.Context, line string) (ExecResult, error)
	// Serve starts a long-lived process inside the guest and returns a handle. The
	// guest's loopback endpoint is forwarded to the host address the handle reports, so
	// a model server in the guest is reachable without giving the guest host network.
	Serve(ctx context.Context, argv []string) (Serving, error)
	// ReadFile reads a file from the guest working area.
	ReadFile(ctx context.Context, p string) ([]byte, error)
	// WriteFile writes a file into the guest working area, creating parents.
	WriteFile(ctx context.Context, p string, data []byte) error
	// List returns the regular-file paths under dir inside the guest, relative to its
	// root. It is the primitive Glob and Walk build on.
	List(ctx context.Context, dir string) ([]string, error)
	// Close shuts the guest down and releases the VM's resources.
	Close() error
}

Machine is a running microVM a driver provides: the minimal primitives the tier needs to use a guest with its own kernel. It is the boundary a hardware-virtualization backend implements, so a backend writes only this surface and the guest is already booted confined to its Guarantees by the driver that created it. Implementations must be safe for concurrent use.

type MicroVM ¶

type MicroVM struct {
	// contains filtered or unexported fields
}

MicroVM is the hardware-virtualization sandbox tier: it implements the Sandbox port over a Machine the host's VMM provides, so isolation runs in a guest with its own kernel. It reports ContainmentMicroVM, the level the gate requires for untrusted work, and confines every file operation to the guest root as defense-in-depth on top of the guest's own boundary, matching the Local and Remote tiers' default-deny rule.

func BootMicroVM(ctx context.Context, spec Spec) (*MicroVM, error)

func BootMicroVMWith(ctx context.Context, d Driver, spec Spec) (*MicroVM, error)

func (v *MicroVM) Close() error

func (v *MicroVM) Containment() Containment

func (v *MicroVM) Driver() string

func (v *MicroVM) Exec(ctx context.Context, cmd Command) (ExecResult, error)

func (v *MicroVM) Glob(ctx context.Context, pattern string) ([]string, error)

func (v *MicroVM) ReadFile(ctx context.Context, p string) ([]byte, error)

func (v *MicroVM) Serve(ctx context.Context, argv []string) (Serving, error)

func (v *MicroVM) Walk(ctx context.Context, root string) ([]string, error)

func (v *MicroVM) WriteFile(ctx context.Context, p string, data []byte) error

type Mount ¶

type Mount struct {
	// HostPath is the absolute host path to expose. It must be absolute so the mount
	// cannot be reinterpreted relative to the guest's working directory.
	HostPath string
	// GuestPath is the absolute path the mount appears at inside the guest.
	GuestPath string
	// ReadOnly gives the guest a read-only view of HostPath. For an untrusted guest
	// every host mount must be read-only.
	ReadOnly bool
}

Mount is a host path exposed inside the guest. Untrusted weights are mounted read-only so the guest cannot tamper with them or use a writable mount to plant a persistent change on the host. A writable host mount into an untrusted guest is a hole in the boundary, so the tier refuses one (see Guarantees.validate).

type OCIEngine ¶

type OCIEngine string

OCIEngine is a container runtime Flynn drives. Both accept the same run flags this tier composes, so the engine choice does not change the security posture, only the binary.

const (
	// EngineDocker is the Docker CLI.
	EngineDocker OCIEngine = "docker"
	// EnginePodman is the Podman CLI, a drop-in for the run flags used here.
	EnginePodman OCIEngine = "podman"
)

type Process ¶

type Process struct {
	// contains filtered or unexported fields
}

Process is a handle to a background process started by Serve. It is safe for concurrent use: Stop, Wait, Done, and Output may be called from any goroutine. The process is not tied to the context passed to Serve; it runs until it exits on its own or Stop is called, so a server outlives the call that started it.

func (p *Process) Done() <-chan struct{}

func (p *Process) Output() string

func (p *Process) PID() int

func (p *Process) Running() bool

func (p *Process) Stop() error

func (p *Process) Wait(ctx context.Context) error

type Remote ¶

type Remote struct {
	// contains filtered or unexported fields
}

Remote is the remote sandbox tier: it implements the Sandbox port by mapping each operation onto a Transport, so isolation runs server-side in a cloud microVM while the host only orchestrates. It is platform-agnostic (the host never executes the work) and the same on Linux, macOS, and Windows. Path confinement is enforced here as defense-in-depth before any call reaches the backend, matching the Local tier's default-deny boundary.

func NewRemote(t Transport) *Remote

func (r *Remote) Close() error

func (r *Remote) Exec(ctx context.Context, cmd Command) (ExecResult, error)

func (r *Remote) Glob(ctx context.Context, pattern string) ([]string, error)

func (r *Remote) ReadFile(ctx context.Context, p string) ([]byte, error)

func (r *Remote) Walk(ctx context.Context, root string) ([]string, error)

func (r *Remote) WriteFile(ctx context.Context, p string, data []byte) error

type ResourceLimits ¶

type ResourceLimits struct {
	// MemoryMiB caps the memory the command (and its job, where the platform caps a
	// tree) may commit, in MiB. Zero applies no memory cap.
	MemoryMiB int
	// MaxProcesses caps how many processes the command may have running at once, a
	// fork-bomb backstop. Zero uses the platform's generous default cap.
	MaxProcesses int
}

ResourceLimits caps a sandboxed command's use of host resources beyond the wall-clock cap (WithExecTimeout): the memory it may commit and the number of processes it may spawn. A zero field applies no cap on that axis, so the zero value changes nothing and the always-on floor stays out of a legitimate build's way. It is the always-present tier's coarse backstop against a memory bomb or a fork storm; the container and microVM tiers enforce hard CPU, memory, and PID caps for untrusted work, where the runtime gives every axis a real cgroup.

Enforcement is per platform and best effort at this tier. Windows applies it through the confined command's job object (a real memory and active-process cap). The Linux and macOS floors do not yet impose it (a per-run cgroup needs cgroup-v2 delegation that is not guaranteed for an unprivileged agent); a command that needs a hard cap there runs under the container or microVM tier.

type Runner ¶

type Runner func(ctx context.Context, argv []string) (stdout string, err error)

Runner runs an OCI engine command to completion and returns its stdout. argv[0] is the engine binary, the rest its arguments. It is injected so the driver's logic is testable with a scripted engine; the default runner execs the CLI.

type Sandbox ¶

type Sandbox interface {
	// Exec runs a command inside the sandbox.
	Exec(ctx context.Context, cmd Command) (ExecResult, error)
	// ReadFile reads a file within the sandbox.
	ReadFile(ctx context.Context, path string) ([]byte, error)
	// WriteFile writes a file within the sandbox, creating parent directories.
	WriteFile(ctx context.Context, path string, data []byte) error
	// Glob lists paths matching a shell pattern within the sandbox, relative to the
	// root.
	Glob(ctx context.Context, pattern string) ([]string, error)
	// Walk returns the regular-file paths under root within the sandbox, relative
	// to the sandbox root.
	Walk(ctx context.Context, root string) ([]string, error)
	// Close releases the sandbox's resources.
	Close() error
}

Sandbox is the execution boundary. All paths are relative to the sandbox root, and an implementation must reject any operation that would reach outside its boundary (default-deny). Implementations must be safe for concurrent use.

Environment isolation is part of the contract: an implementation must not pass the agent's process environment through to a command it runs. A command sees only a minimal, credential-free baseline plus variables granted to it explicitly, so a secret the agent holds can never leak into a command's environment by default. This is the execution-boundary half of the project's "secrets are never materialized into the agent's environment" invariant.

func Select(t Trust, candidates ...Sandbox) (Sandbox, error)

type ServeSpec ¶

type ServeSpec struct {
	// Argv is the program and its arguments, executed directly without a shell. Argv[0]
	// is the binary to run; the rest are passed verbatim.
	Argv []string
	// Confine requests the platform's kernel confinement (a read-only host and the
	// syscall filter) for the process where the Local was built to provide it. Network
	// is deliberately left reachable so a loopback server the process binds stays
	// reachable from this host; denying outbound egress while keeping loopback is a
	// separate, finer policy layered on top, not part of starting the server.
	Confine bool
}

ServeSpec describes a long-lived process to run in the background inside the sandbox. It is the counterpart of Command for a server that must keep running and be reached over a loopback port, rather than a one-shot command whose output is collected and returned. The program is run directly from its argv, never through a shell, so a model id or weights path in the arguments cannot be reinterpreted as shell syntax.

type Serving ¶

type Serving interface {
	// Addr is the host loopback address (host:port) the guest's server is reachable at.
	Addr() string
	// Running reports whether the server has not yet exited.
	Running() bool
	// Output returns the retained tail of the server's combined output, for diagnostics.
	Output() string
	// Done is closed when the server exits.
	Done() <-chan struct{}
	// Stop ends the server and tears down its guest. It is idempotent.
	Stop() error
}

Serving is a handle to a long-lived server running inside a guest. It mirrors the background-process contract the serve layer consumes, but the address is a host loopback endpoint forwarded into the guest rather than a direct host port.

func RunContainer(ctx context.Context, spec ContainerSpec) (Serving, error)

func RunContainerWith(ctx context.Context, d ContainerDriver, spec ContainerSpec) (Serving, error)

type Session ¶ added in v0.1.3

type Session struct {
	// contains filtered or unexported fields
}

Session is a running confined subprocess whose stdin and stdout are live pipes and whose stderr is retained as a bounded tail for diagnostics. It is safe for concurrent use: Stdin, Stdout, Stderr, Wait, and Stop may be called from any goroutine. The process runs until it exits on its own or Stop is called; Stop kills it and releases its resources, so an extension leaves no orphan when it is disabled or the host shuts down.

func (s *Session) Stderr() string

func (s *Session) Stdin() io.WriteCloser

func (s *Session) Stdout() io.Reader

func (s *Session) Stop() error

func (s *Session) Wait() error

type SessionSpec ¶ added in v0.1.3

type SessionSpec struct {
	// Argv is the program and its arguments, executed directly without a shell. Argv[0] is
	// the binary to run; the rest are passed verbatim. For an extension it is a fixed,
	// signature-verified path with fixed arguments, never model-influenced.
	Argv []string
	// Env grants additional KEY=VALUE variables on top of the deny-by-default baseline. A
	// granted value overrides the baseline value for the same key. An extension is launched
	// with a minimal env and no secrets; a scoped bridge token, when one is needed, reaches
	// the child here rather than on the command line.
	Env []string
	// Confine requests the platform's kernel confinement (a read-only host and the syscall
	// filter, plus the network isolation the Local was configured for). It composes with a
	// governed-egress Local: when egress is configured the launch is confined regardless of
	// this flag, so the OS-level denial that pins the child to the proxy is always in force.
	Confine bool
}

SessionSpec describes a long-lived process to run inside the sandbox with BOTH its standard input and output held open as live pipes, for a caller that carries on a request/response conversation with the process over its own stdio. It is the duplex counterpart of Stream (stdin written once then closed, stdout streamed) and Serve (backgrounded, reached over a loopback port): the out-of-process extension host speaks MCP JSON-RPC to a subprocess and must both write requests to it and read replies from it for the life of the process.

The channel is deliberately the process's own anonymous stdio pipes and nothing else: a pipe fd is private to this parent and its child, where a loopback port any co-located process could bind or capture is not, so an extension cannot be snooped or injected on its channel. The program is run directly from Argv, never through a shell, so nothing in the arguments can be reinterpreted as shell syntax, and the deny-by-default environment applies exactly as for Exec, Stream, and Serve: the host environment is never inherited, so no secret the agent holds reaches the process unless Env grants it by name.

type Spec ¶

type Spec struct {
	// Root is the host working directory the guest's output and staging area live in.
	// File operations through the Sandbox port are confined to it, the same default-deny
	// boundary the Local and Remote tiers enforce.
	Root string
	// Image is the guest kernel and root filesystem to boot.
	Image Image
	// Guarantees is the security composition the guest must run under.
	Guarantees Guarantees
}

Spec is a request to boot a confined guest: where its working area lives on the host, which image to boot, and the guarantees it runs under.

type StreamProcess ¶

type StreamProcess struct {
	// contains filtered or unexported fields
}

StreamProcess is a running confined subprocess: its stdout as a live stream plus a wait handle. Its lifetime is bound to the context passed to Stream, so cancelling that context (a halt or a shutdown) kills the process and Wait then returns. Stdout must be drained for the process to make progress; Wait blocks until the process ends and returns its outcome (nil on a clean exit, a non-nil error on a non-zero exit or a context-driven kill). A caller that has finished reading before the process exits calls Wait to release its resources.

func (p *StreamProcess) Stdout() io.Reader

func (p *StreamProcess) Wait() error

type StreamSpec ¶

type StreamSpec struct {
	// Argv is the program and its arguments, executed directly without a shell. Argv[0]
	// is the binary to run; the rest are passed verbatim.
	Argv []string
	// Stdin, when non-empty, is written to the process's standard input and the stream is
	// then closed. Like Command.Stdin it keeps a secret off the command line: the value
	// travels only on the pipe, never in argv or a log.
	Stdin []byte
	// Env grants additional KEY=VALUE variables on top of the sandbox's deny-by-default
	// baseline, the same brokered path WithEnv feeds a one-shot command. A granted value
	// overrides the baseline value for the same key. It is how a scoped, single-episode
	// bridge token reaches the child without ever touching the command line.
	Env []string
	// Confine requests the platform's kernel confinement (a read-only host and the syscall
	// filter, plus the network isolation the Local was configured for). It composes with a
	// governed-egress Local: when egress is configured the launch is confined regardless of
	// this flag, so the OS-level denial that pins the child to the proxy is always in force.
	Confine bool
}

StreamSpec is a program to launch under the sandbox with its stdout delivered as a live stream and its lifetime bound to a context, for a caller that reads the process's output as it is produced and stops it on a halt. It is the streaming counterpart of Command (one-shot, combined output collected and returned) and ServeSpec (backgrounded, only a buffered tail kept): the external-agent episode host reads an agent CLI's newline-delimited event stream and kills the CLI when the run halts.

The program is run directly from its Argv, never through a shell, so a model id, a path, or any other value in the arguments cannot be reinterpreted as shell syntax. The deny-by-default environment applies exactly as it does to Exec and Serve: the host environment is never inherited, so no secret the agent holds reaches the process unless Env grants it by name.

type Transport ¶

type Transport interface {
	// Exec runs a shell command in the remote working directory. A non-zero exit is
	// a result (in ExecResult.ExitCode), not an error; an error means the command
	// could not be run.
	Exec(ctx context.Context, line string) (ExecResult, error)
	// ReadFile reads a file from the remote working directory.
	ReadFile(ctx context.Context, p string) ([]byte, error)
	// WriteFile writes a file in the remote working directory, creating parents.
	WriteFile(ctx context.Context, p string, data []byte) error
	// List returns the regular-file paths under dir (recursive), relative to the
	// remote root. It is the primitive Glob and Walk build on, so a backend exposes
	// one listing call rather than two.
	List(ctx context.Context, dir string) ([]string, error)
	// Close tears down the remote sandbox and releases its resources.
	Close(ctx context.Context) error
}

Transport is the minimal set of primitives a remote sandbox backend provides: run a command, move a file in or out, list files, and tear the sandbox down. It is the Flynn-owned port each cloud backend (E2B, Daytona, Modal, ...) implements over its own API or CLI, so a backend writes only this surface and inherits the full Sandbox port through Remote. Paths are relative to the remote sandbox root; the backend confines them server-side, and Remote adds a default-deny check on top so confinement never depends on the backend alone.

type Trust ¶

type Trust int

Trust is how far the code about to run is trusted, which sets the containment it requires.

const (
	// TrustTrusted is the agent's own built-in tools: code we ship and vet.
	TrustTrusted Trust = iota
	// TrustSemi is code the model authored this run (a shell command, a script):
	// not hostile by construction, but not vetted either.
	TrustSemi
	// TrustUntrusted is code from outside that we cannot vouch for: a downloaded
	// model's weights parsed by a runtime with a history of remote-code-execution
	// flaws, or an unsigned plugin. The worst case is host compromise.
	TrustUntrusted
)

func (t Trust) String() string