sandbox

package
v0.1.28 Latest Latest
Warning

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

Go to latest
Published: Feb 28, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package sandbox provides the core sandbox VM management functionality.

Index

Constants

This section is empty.

Variables

View Source
var (
	// Exec relay errors
	ErrRelayConnect    = errors.New("connect to exec relay")
	ErrRelaySend       = errors.New("send exec request")
	ErrRelayRead       = errors.New("read exec result")
	ErrRelayUnexpected = errors.New("unexpected message type")
	ErrRelayDecode     = errors.New("decode exec result")
	ErrRelayListen     = errors.New("listen on relay socket")
	ErrRelayProxy      = errors.New("relay port-forward proxy")

	// Rootfs errors
	ErrGuestAgent   = errors.New("guest-agent not found")
	ErrGuestFused   = errors.New("guest-fused not found")
	ErrGuestInit    = errors.New("guest-init not found")
	ErrResizeRootfs = errors.New("resize rootfs")
	ErrCreateRootfs = errors.New("create rootfs image")
	ErrCreateTemp   = errors.New("create temp file")
	ErrWriteTemp    = errors.New("write temp file")
	ErrDebugfs      = errors.New("debugfs")
	ErrStatRootfs   = errors.New("stat rootfs")
	ErrTruncate     = errors.New("truncate rootfs")
	ErrResize2fs    = errors.New("resize2fs")

	// Sandbox lifecycle errors (shared between darwin and linux)
	ErrRegisterState          = errors.New("register VM state")
	ErrAllocateSubnet         = errors.New("allocate subnet")
	ErrCreateCAPool           = errors.New("create CA pool")
	ErrCopyRootfs             = errors.New("copy rootfs")
	ErrPrepareRootfs          = errors.New("prepare rootfs")
	ErrPrepareBootstrapRoot   = errors.New("prepare bootstrap rootfs")
	ErrInjectCACert           = errors.New("inject CA cert into rootfs")
	ErrInvalidDiskCfg         = errors.New("invalid extra disk config")
	ErrCreateVM               = errors.New("create VM")
	ErrCreateProxy            = errors.New("create transparent proxy")
	ErrFirewallSetup          = errors.New("setup firewall rules")
	ErrNetworkStack           = errors.New("create network stack")
	ErrVFSListener            = errors.New("setup VFS listener")
	ErrVFSServer              = errors.New("start VFS server")
	ErrMachineClose           = errors.New("machine close")
	ErrPrepareOverlayMount    = errors.New("prepare overlay mount snapshot")
	ErrCopyOverlaySource      = errors.New("copy overlay mount source")
	ErrRemoveOverlaySnapshot  = errors.New("remove overlay mount snapshot")
	ErrOverlayLayerLimit      = errors.New("overlay layer limit exceeded")
	ErrOverlayDiskLimit       = errors.New("overlay disk device limit exceeded")
	ErrFirewallCleanup        = errors.New("firewall cleanup")
	ErrNATCleanup             = errors.New("NAT cleanup")
	ErrNetworkFile            = errors.New("get network file")
	ErrReleaseSubnet          = errors.New("release subnet")
	ErrUnregisterState        = errors.New("unregister VM state")
	ErrRemoveRootfs           = errors.New("remove rootfs copy")
	ErrProxyClose             = errors.New("proxy close")
	ErrLifecycleInit          = errors.New("initialize lifecycle record")
	ErrLifecycleUpdate        = errors.New("update lifecycle record")
	ErrPortForwardDial        = errors.New("dial guest port-forward service")
	ErrPortForwardInit        = errors.New("initialize guest port-forward")
	ErrPortForwardBind        = errors.New("bind local port-forward listener")
	ErrPortForwardCopy        = errors.New("proxy port-forward stream")
	ErrNoVsockDialer          = errors.New("vm backend does not support vsock dial")
	ErrVFSDisabled            = errors.New("vfs is disabled")
	ErrAllowListUnavailable   = errors.New("allow-list updates unavailable")
	ErrAllowListHosts         = errors.New("invalid allow-list hosts")
	ErrInteractiveUnsupported = errors.New("interactive exec unsupported")
)

Sentinel errors for the sandbox package.

Functions

func DefaultGuestAgentPath

func DefaultGuestAgentPath() string

DefaultGuestAgentPath returns the default path to guest-agent binary.

func DefaultGuestFusedPath

func DefaultGuestFusedPath() string

DefaultGuestFusedPath returns the default path to guest-fused binary.

func DefaultGuestInitPath added in v0.1.20

func DefaultGuestInitPath() string

DefaultGuestInitPath returns the default path to guest-init binary.

func DefaultInitramfsPath

func DefaultInitramfsPath() string

DefaultInitramfsPath returns the default path to the initramfs image (optional, mainly for macOS).

func DefaultKernelPath

func DefaultKernelPath() string

DefaultKernelPath returns the path to the kernel image, downloading if needed. It checks in order: MATCHLOCK_KERNEL env, legacy paths, then downloads from OCI.

func DefaultKernelPathWithVersion

func DefaultKernelPathWithVersion(version string) (string, error)

DefaultKernelPathWithVersion returns the path to a specific kernel version.

func ExecInteractiveViaRelay

func ExecInteractiveViaRelay(ctx context.Context, socketPath, command, workingDir, user string, rows, cols uint16, stdin io.Reader, stdout io.Writer) (int, error)

ExecInteractiveViaRelay connects to an exec relay socket and runs an interactive command.

func ExecPipeViaRelay added in v0.1.12

func ExecPipeViaRelay(ctx context.Context, socketPath, command, workingDir, user string, stdin io.Reader, stdout, stderr io.Writer) (int, error)

ExecPipeViaRelay connects to an exec relay socket and runs a command with bidirectional stdin/stdout/stderr piping (no PTY).

func ExecViaRelay

func ExecViaRelay(ctx context.Context, socketPath, command, workingDir, user string) (*api.ExecResult, error)

ExecViaRelay connects to an exec relay socket and runs a command. The context controls the lifetime — if cancelled, the connection is closed.

func KernelArch

func KernelArch() string

KernelArch returns the current kernel architecture.

func KernelVersion

func KernelVersion() string

KernelVersion returns the current kernel version.

func PortForwardViaRelay added in v0.1.20

func PortForwardViaRelay(ctx context.Context, relaySocketPath string, remotePort int, localConn net.Conn) error

PortForwardViaRelay proxies one local TCP connection through the run-process relay socket into the guest remote port.

Types

type AllowListUpdateResult added in v0.1.24

type AllowListUpdateResult struct {
	AllowedHosts []string
	Added        []string
	Removed      []string
}

func AllowListAddViaRelay added in v0.1.24

func AllowListAddViaRelay(ctx context.Context, socketPath string, hosts []string) (*AllowListUpdateResult, error)

func AllowListDeleteViaRelay added in v0.1.24

func AllowListDeleteViaRelay(ctx context.Context, socketPath string, hosts []string) (*AllowListUpdateResult, error)

type ExecRelay

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

ExecRelay serves exec requests from external processes via a Unix socket. This allows `matchlock exec` to run commands in a VM owned by another process.

func NewExecRelay

func NewExecRelay(sb *Sandbox) *ExecRelay

func (*ExecRelay) Start

func (r *ExecRelay) Start(socketPath string) error

func (*ExecRelay) Stop

func (r *ExecRelay) Stop()

type FirewallRules

type FirewallRules interface {
	Setup() error
	Cleanup() error
}

FirewallRules is an interface for managing firewall rules.

type Options

type Options struct {
	// KernelPath overrides the default kernel path
	KernelPath string
	// RootfsPaths are immutable lower image paths in base->top order (required).
	RootfsPaths []string
	// RootfsFSTypes optionally declares filesystem type per lower image.
	RootfsFSTypes []string
}

Options configures sandbox creation.

type PortForwardManager added in v0.1.20

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

PortForwardManager manages host listeners that proxy traffic into a sandbox.

func (*PortForwardManager) Bindings added in v0.1.20

func (m *PortForwardManager) Bindings() []api.PortForwardBinding

Bindings returns the active listener bindings.

func (*PortForwardManager) Close added in v0.1.20

func (m *PortForwardManager) Close() error

Close stops all listeners and waits for active proxy loops to exit.

type Sandbox

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

Sandbox represents a running sandbox VM with all associated resources.

func New

func New(ctx context.Context, config *api.Config, opts *Options) (sb *Sandbox, retErr error)

New creates a new sandbox VM with the given configuration.

func (*Sandbox) AddAllowedHosts added in v0.1.24

func (s *Sandbox) AddAllowedHosts(ctx context.Context, hosts []string) ([]string, error)

func (*Sandbox) AllowedHosts added in v0.1.24

func (s *Sandbox) AllowedHosts(ctx context.Context) ([]string, error)

func (*Sandbox) CAPool added in v0.1.1

func (s *Sandbox) CAPool() *sandboxnet.CAPool

func (*Sandbox) Close

func (s *Sandbox) Close(ctx context.Context) error

Close shuts down the sandbox and releases all resources.

func (*Sandbox) Config

func (s *Sandbox) Config() *api.Config

Config returns the sandbox configuration.

func (*Sandbox) Events

func (s *Sandbox) Events() <-chan api.Event

Events returns a channel for receiving sandbox events.

func (*Sandbox) Exec

func (s *Sandbox) Exec(ctx context.Context, command string, opts *api.ExecOptions) (*api.ExecResult, error)

func (*Sandbox) ExecInteractive added in v0.1.26

func (s *Sandbox) ExecInteractive(ctx context.Context, command string, opts *api.ExecOptions, rows, cols uint16, stdin io.Reader, stdout io.Writer, resizeCh <-chan [2]uint16) (int, error)

func (*Sandbox) ID

func (s *Sandbox) ID() string

ID returns the sandbox identifier.

func (*Sandbox) ListFiles

func (s *Sandbox) ListFiles(ctx context.Context, path string) ([]api.FileInfo, error)

func (*Sandbox) Machine

func (s *Sandbox) Machine() vm.Machine

Machine returns the underlying VM machine for advanced operations.

func (*Sandbox) Policy

func (s *Sandbox) Policy() *policy.Engine

Policy returns the policy engine.

func (*Sandbox) PrepareExecEnv added in v0.1.1

func (s *Sandbox) PrepareExecEnv() *api.ExecOptions

func (*Sandbox) ReadFile

func (s *Sandbox) ReadFile(ctx context.Context, path string) ([]byte, error)

func (*Sandbox) ReadFileTo added in v0.1.4

func (s *Sandbox) ReadFileTo(ctx context.Context, path string, w io.Writer) (int64, error)

func (*Sandbox) RemoveAllowedHosts added in v0.1.24

func (s *Sandbox) RemoveAllowedHosts(ctx context.Context, hosts []string) ([]string, error)

func (*Sandbox) Start

func (s *Sandbox) Start(ctx context.Context) error

Start starts the sandbox VM.

func (*Sandbox) StartPortForwards added in v0.1.20

func (s *Sandbox) StartPortForwards(ctx context.Context, addresses []string, forwards []api.PortForward) (*PortForwardManager, error)

StartPortForwards starts local listeners and proxies connections to the guest.

func (*Sandbox) Stop

func (s *Sandbox) Stop(ctx context.Context) error

Stop stops the sandbox VM.

func (*Sandbox) Workspace

func (s *Sandbox) Workspace() string

Workspace returns the VFS mount point path.

func (*Sandbox) WriteFile

func (s *Sandbox) WriteFile(ctx context.Context, path string, content []byte, mode uint32) error

Jump to

Keyboard shortcuts

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