sdk

package
v0.2.9 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package sdk provides a client for interacting with Matchlock sandboxes via JSON-RPC.

Use the builder API for a fluent experience: 

client, err := sdk.NewClient(sdk.DefaultConfig())
if err != nil {
    log.Fatal(err)
}
defer client.Close(0)

sandbox := sdk.New("python:3.12-alpine").
    WithCPUs(2).
    WithMemory(1024).
    AllowHost("dl-cdn.alpinelinux.org", "api.openai.com").
    AddHost("api.internal", "10.0.0.10").
    AddSecret("API_KEY", os.Getenv("API_KEY"), "api.openai.com")

vmID, err := client.Launch(sandbox)

result, err := client.Exec(ctx, "echo hello")
fmt.Println(result.Stdout)

Index

Constants

View Source 
const (
	ErrCodeParse          = -32700
	ErrCodeInvalidRequest = -32600
	ErrCodeMethodNotFound = -32601
	ErrCodeInvalidParams  = -32602
	ErrCodeInternal       = -32603
	ErrCodeVMFailed       = -32000
	ErrCodeExecFailed     = -32001
	ErrCodeFileFailed     = -32002
	ErrCodeCancelled      = -32003
)

Error codes

Variables

View Source 
var (
	ErrStdinPipe  = errors.New("get stdin pipe")
	ErrStdoutPipe = errors.New("get stdout pipe")
	ErrStderrPipe = errors.New("get stderr pipe")
	ErrStartProc  = errors.New("start matchlock")
)

Process / pipe errors (NewClient)

View Source 
var (
	ErrClientClosed    = errors.New("client is closed")
	ErrMarshalRequest  = errors.New("marshal request")
	ErrWriteRequest    = errors.New("write request")
	ErrConnectionClose = errors.New("connection closed")
)

Request lifecycle errors (sendRequestCtx, startReader)

View Source 
var (
	ErrImageRequired      = errors.New("image is required (e.g., alpine:latest)")
	ErrInvalidCPUCount    = errors.New("cpu count must be > 0")
	ErrInvalidNetworkMTU  = errors.New("network mtu must be > 0")
	ErrNoNetworkConflict  = errors.New("no network cannot be combined with allowed hosts, secrets, forced interception, or network interception rules")
	ErrInvalidAddHost     = errors.New("invalid add-host mapping")
	ErrInvalidNetworkHook = errors.New("invalid network hook")
	ErrParseCreateResult  = errors.New("parse create result")
	ErrInvalidVFSHook     = errors.New("invalid vfs hook")
	ErrVFSHookBlocked     = errors.New("vfs hook blocked operation")
	ErrParsePortForwards  = errors.New("parse port-forward spec")
	ErrParsePortBindings  = errors.New("parse port-forward result")
)

Create / VM errors

View Source 
var (
	ErrParseExecResult       = errors.New("parse exec result")
	ErrParseExecStreamResult = errors.New("parse exec_stream result")
	ErrParseExecPipeResult   = errors.New("parse exec_pipe result")
	ErrParseExecTTYResult    = errors.New("parse exec_tty result")
	ErrParseLogResult        = errors.New("parse log result")
)

Exec errors

View Source 
var (
	ErrParseReadResult = errors.New("parse read result")
	ErrParseListResult = errors.New("parse list result")
	ErrAllowListHosts  = errors.New("allow-list hosts are required")
	ErrParseAllowList  = errors.New("parse allow-list result")
)

File operation errors

View Source 
var (
	ErrCloseTimeout            = errors.New("close timed out, process killed")
	ErrRemoveVM                = errors.New("matchlock rm")
	ErrBinaryPathRequired      = errors.New("matchlock binary path is required")
	ErrVolumeNameRequired      = errors.New("volume name is required")
	ErrInvalidVolumeSize       = errors.New("volume size must be > 0")
	ErrVolumeCommand           = errors.New("matchlock volume command")
	ErrParseVolumeCreateResult = errors.New("parse volume create result")
	ErrParseVolumeListResult   = errors.New("parse volume list result")
)

Close / Remove errors

Functions

This section is empty.

Types

type AllowListUpdate added in v0.1.24 

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

type Client 

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

Client is a Matchlock JSON-RPC client. All methods are safe for concurrent use.

func NewClient 

func NewClient(cfg Config) (*Client, error)

NewClient creates a new Matchlock client and starts the RPC process

func (*Client) AllowListAdd added in v0.1.24 

func (c *Client) AllowListAdd(ctx context.Context, hosts ...string) (*AllowListUpdate, error)

func (*Client) AllowListDelete added in v0.1.24 

func (c *Client) AllowListDelete(ctx context.Context, hosts ...string) (*AllowListUpdate, error)

func (*Client) Close 

func (c *Client) Close(timeout time.Duration) error

Close closes the sandbox and cleans up resources. The VM state directory is preserved so it appears in "matchlock list". Call Remove after Close to delete the state entirely.

timeout controls how long to wait for the process to exit after sending the close request. A zero value uses a short grace period and then force-kills if needed. When a non-zero timeout expires, the process is forcefully killed.

func (*Client) Create 

func (c *Client) Create(opts CreateOptions) (string, error)

func (*Client) Exec 

func (c *Client) Exec(ctx context.Context, command string) (*ExecResult, error)

Exec executes a command in the sandbox and returns the buffered result. The context controls the lifetime of the request — if cancelled, a cancel RPC is sent to abort the in-flight execution.

func (*Client) ExecInteractive added in v0.1.26 

func (c *Client) ExecInteractive(ctx context.Context, command string, opts *ExecInteractiveOptions) (*ExecInteractiveResult, error)

ExecInteractive executes a command in TTY mode (equivalent to CLI -it behavior).

func (*Client) ExecPipe added in v0.1.26 

func (c *Client) ExecPipe(ctx context.Context, command string, stdin io.Reader, stdout, stderr io.Writer) (*ExecPipeResult, error)

ExecPipe executes a command in pipe mode with bidirectional stdin/stdout/stderr. This mode does not allocate a PTY.

func (*Client) ExecPipeWithDir added in v0.1.26 

func (c *Client) ExecPipeWithDir(ctx context.Context, command, workingDir string, stdin io.Reader, stdout, stderr io.Writer) (*ExecPipeResult, error)

ExecPipeWithDir executes a command in pipe mode with a working directory.

func (*Client) ExecStream 

func (c *Client) ExecStream(ctx context.Context, command string, stdout, stderr io.Writer) (*ExecStreamResult, error)

ExecStream executes a command and streams stdout/stderr to the provided writers in real-time. If stdout or stderr is nil, that stream is discarded. The final ExecStreamResult contains only the exit code and duration.

func (*Client) ExecStreamWithDir 

func (c *Client) ExecStreamWithDir(ctx context.Context, command, workingDir string, stdout, stderr io.Writer) (*ExecStreamResult, error)

ExecStreamWithDir executes a command with a working directory and streams stdout/stderr to the provided writers in real-time.

func (*Client) ExecWithDir 

func (c *Client) ExecWithDir(ctx context.Context, command, workingDir string) (*ExecResult, error)

ExecWithDir executes a command in the sandbox with a working directory.

func (*Client) Launch 

func (c *Client) Launch(b *SandboxBuilder) (string, error)

Launch creates and starts the sandbox using the given client. This is a convenience that calls client.Create(b.Options()) and starts the image ENTRYPOINT/CMD in detached mode.

func (*Client) ListFiles 

func (c *Client) ListFiles(ctx context.Context, path string) ([]FileInfo, error)

ListFiles lists files in a directory.

func (*Client) Log added in v0.2.4 

func (c *Client) Log(ctx context.Context) (string, error)

Log returns the buffered VM log content.

func (*Client) LogStream added in v0.2.4 

func (c *Client) LogStream(ctx context.Context, stdout io.Writer) error

LogStream writes the current VM log to stdout and continues streaming newly appended data until ctx is cancelled.

func (*Client) PortForward added in v0.1.20 

func (c *Client) PortForward(ctx context.Context, specs ...string) ([]api.PortForwardBinding, error)

func (*Client) PortForwardWithAddresses added in v0.1.20 

func (c *Client) PortForwardWithAddresses(ctx context.Context, addresses []string, specs ...string) ([]api.PortForwardBinding, error)

PortForwardWithAddresses applies one or more [LOCAL_PORT:]REMOTE_PORT mappings bound on the provided host addresses.

func (*Client) ReadFile 

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

ReadFile reads a file from the sandbox.

func (*Client) Remove 

func (c *Client) Remove() error

Remove deletes the stopped VM state directory. Must be called after Close. Uses the matchlock CLI binary that was configured in Config.BinaryPath.

func (*Client) VMID 

func (c *Client) VMID() string

VMID returns the ID of the current VM, or empty string if none created

func (*Client) VolumeCreate added in v0.1.24 

func (c *Client) VolumeCreate(name string, sizeMB int) (*VolumeInfo, error)

VolumeCreate creates a named raw ext4 volume and returns its metadata.

func (*Client) VolumeList added in v0.1.24 

func (c *Client) VolumeList() ([]VolumeInfo, error)

VolumeList returns all named raw ext4 volumes.

func (*Client) VolumeRemove added in v0.1.24 

func (c *Client) VolumeRemove(name string) error

VolumeRemove removes a named raw ext4 volume.

func (*Client) WriteFile 

func (c *Client) WriteFile(ctx context.Context, path string, content []byte) error

func (*Client) WriteFileMode 

func (c *Client) WriteFileMode(ctx context.Context, path string, content []byte, mode uint32) error

WriteFileMode writes content to a file with specific permissions.

type Config 

type Config struct {
	// BinaryPath is the path to the matchlock binary
	BinaryPath string
	// UseSudo runs matchlock with sudo (required for TAP devices)
	UseSudo bool
}

Config holds client configuration

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default client configuration

type CreateOptions 

type CreateOptions struct {
	// Image is the container image reference (required, e.g., alpine:latest)
	Image string
	// KernelRef selects the guest kernel to boot.
	// Supports empty (default), file:///absolute/path, or OCI image refs.
	KernelRef string
	// Privileged skips in-guest security restrictions (seccomp, cap drop, no_new_privs)
	Privileged bool
	// CPUs is the number of vCPUs
	CPUs float64
	// MemoryMB is the memory in megabytes
	MemoryMB int
	// DiskSizeMB is the disk size in megabytes (default: 5120)
	DiskSizeMB int
	// TimeoutSeconds is the maximum execution time
	TimeoutSeconds int
	// AllowedHosts is a list of allowed network hosts (supports wildcards)
	AllowedHosts []string
	// AddHosts injects static host-to-IP mappings into guest /etc/hosts.
	AddHosts []api.HostIPMapping
	// BlockPrivateIPs controls access to private IP ranges.
	// Use together with BlockPrivateIPsSet to express explicit true/false.
	BlockPrivateIPs bool
	// BlockPrivateIPsSet marks whether BlockPrivateIPs was explicitly set.
	// When false, the SDK preserves API defaults for private IP blocking.
	BlockPrivateIPsSet bool
	// NoNetwork disables guest network egress entirely (no guest NIC).
	NoNetwork bool
	// ForceInterception forces network interception even when allow-list/secrets are empty.
	ForceInterception bool
	// NetworkInterception configures host-side network interception rules.
	NetworkInterception *NetworkInterceptionConfig
	// Mounts defines VFS mount configurations
	Mounts map[string]MountConfig
	// Env defines non-secret environment variables for command execution.
	// These are visible in VM state and inspect/get outputs.
	Env map[string]string
	// Secrets defines secrets to inject (replaced in HTTP requests to allowed hosts)
	Secrets []Secret
	// Workspace is the mount point for VFS in the guest.
	// This must be set when Mounts is non-empty.
	Workspace string
	// VFSInterception configures host-side VFS interception hooks/rules.
	VFSInterception *VFSInterceptionConfig
	// DNSServers overrides the default DNS servers (8.8.8.8, 8.8.4.4)
	DNSServers []string
	// Hostname overrides the default guest hostname (sandbox's ID)
	Hostname string
	// NetworkMTU overrides the guest interface/network stack MTU (default: 1500).
	NetworkMTU int
	// PortForwards maps local host ports to remote sandbox ports.
	// These are applied after VM creation via the port_forward RPC.
	PortForwards []api.PortForward
	// PortForwardAddresses controls host bind addresses used when applying
	// PortForwards (default: 127.0.0.1).
	PortForwardAddresses []string
	// ImageConfig holds OCI image metadata (USER, ENTRYPOINT, CMD, WORKDIR, ENV)
	ImageConfig *ImageConfig
	// LaunchEntrypoint starts image ENTRYPOINT/CMD in detached mode during create.
	// Set by Client.Launch; low-level Create keeps this false unless requested.
	LaunchEntrypoint bool
}

type ExecInteractiveOptions added in v0.1.26 

type ExecInteractiveOptions struct {
	WorkingDir string
	User       string
	Rows       uint16
	Cols       uint16
	Stdin      io.Reader
	Stdout     io.Writer
	Resize     <-chan [2]uint16
}

ExecInteractiveOptions controls interactive TTY execution.

type ExecInteractiveResult added in v0.1.26 

type ExecInteractiveResult struct {
	ExitCode   int
	DurationMS int64
}

ExecInteractiveResult holds the final result of an interactive TTY exec.

type ExecPipeResult added in v0.1.26 

type ExecPipeResult struct {
	ExitCode   int
	DurationMS int64
}

ExecPipeResult holds the final result of a pipe-mode exec.

type ExecResult 

type ExecResult struct {
	// ExitCode is the command's exit code
	ExitCode int
	// Stdout is the standard output
	Stdout string
	// Stderr is the standard error
	Stderr string
	// DurationMS is the execution time in milliseconds
	DurationMS int64
}

type ExecStreamResult 

type ExecStreamResult struct {
	ExitCode   int
	DurationMS int64
}

ExecStreamResult holds the final result of a streaming exec (no stdout/stderr since those were delivered via the callback).

type FileInfo 

type FileInfo struct {
	Name  string `json:"name"`
	Size  int64  `json:"size"`
	Mode  uint32 `json:"mode"`
	IsDir bool   `json:"is_dir"`
}

FileInfo holds file metadata

type ImageConfig added in v0.1.10 

type ImageConfig struct {
	User       string            `json:"user,omitempty"`
	WorkingDir string            `json:"working_dir,omitempty"`
	Entrypoint []string          `json:"entrypoint,omitempty"`
	Cmd        []string          `json:"cmd,omitempty"`
	Env        map[string]string `json:"env,omitempty"`
}

ImageConfig holds OCI image metadata for user/entrypoint/cmd/workdir/env.

type MountConfig 

type MountConfig struct {
	Type     string `json:"type"` // memory, host_fs, overlay
	HostPath string `json:"host_path,omitempty"`
	Readonly bool   `json:"readonly,omitempty"`
}

MountConfig defines a VFS mount

type NetworkBodyTransform added in v0.1.24 

type NetworkBodyTransform struct {
	Find    string `json:"find"`
	Replace string `json:"replace,omitempty"`
}

NetworkBodyTransform applies a literal response-body replacement. For SSE responses, replacements are applied to each `data:` line payload.

type NetworkHookAction added in v0.1.24 

type NetworkHookAction = string

Network hook actions. 

const (
	NetworkHookActionAllow  NetworkHookAction = "allow"
	NetworkHookActionBlock  NetworkHookAction = "block"
	NetworkHookActionMutate NetworkHookAction = "mutate"
)

type NetworkHookFunc added in v0.1.24 

type NetworkHookFunc func(ctx context.Context, req NetworkHookRequest) (*NetworkHookResult, error)

NetworkHookFunc executes in the SDK process for matching network hook rules.

type NetworkHookPhase added in v0.1.24 

type NetworkHookPhase = string

Network hook phases. 

const (
	NetworkHookPhaseBefore NetworkHookPhase = "before"
	NetworkHookPhaseAfter  NetworkHookPhase = "after"
)

type NetworkHookRequest added in v0.1.24 

type NetworkHookRequest struct {
	Phase  NetworkHookPhase
	Host   string
	Method string
	Path   string

	Query          map[string]string
	RequestHeaders map[string][]string

	StatusCode      int
	ResponseHeaders map[string][]string
	IsSSE           bool
}

NetworkHookRequest is passed to an SDK-local network callback hook after static host/method/path prefiltering.

type NetworkHookRequestMutation added in v0.1.24 

type NetworkHookRequestMutation struct {
	// Headers replaces the full outbound request header map when non-nil.
	Headers map[string][]string
	// Query replaces the full outbound query map when non-nil.
	Query map[string]string
	// Path rewrites the outbound request path when non-empty.
	Path string
}

NetworkHookRequestMutation describes request-shaping changes returned by a network callback.

type NetworkHookResponseMutation added in v0.1.24 

type NetworkHookResponseMutation struct {
	// Headers replaces the full inbound response header map when non-nil.
	Headers map[string][]string

	BodyReplacements []NetworkBodyTransform

	// SetBody replaces the entire response body when non-nil.
	SetBody []byte
}

NetworkHookResponseMutation describes response-shaping changes returned by a network callback.

type NetworkHookResult added in v0.1.24 

type NetworkHookResult struct {
	Action NetworkHookAction

	Request  *NetworkHookRequestMutation
	Response *NetworkHookResponseMutation
}

NetworkHookResult describes dynamic mutations returned by an SDK-local network callback hook.

type NetworkHookRule added in v0.1.24 

type NetworkHookRule struct {
	Name    string            `json:"name,omitempty"`
	Phase   NetworkHookPhase  `json:"phase,omitempty"`
	Hosts   []string          `json:"hosts,omitempty"`
	Methods []string          `json:"methods,omitempty"`
	Path    string            `json:"path,omitempty"`
	Action  NetworkHookAction `json:"action,omitempty"`

	SetHeaders    map[string]string `json:"set_headers,omitempty"`
	DeleteHeaders []string          `json:"delete_headers,omitempty"`
	SetQuery      map[string]string `json:"set_query,omitempty"`
	DeleteQuery   []string          `json:"delete_query,omitempty"`
	RewritePath   string            `json:"rewrite_path,omitempty"`

	SetResponseHeaders    map[string]string      `json:"set_response_headers,omitempty"`
	DeleteResponseHeaders []string               `json:"delete_response_headers,omitempty"`
	BodyReplacements      []NetworkBodyTransform `json:"body_replacements,omitempty"`
	TimeoutMS             int                    `json:"timeout_ms,omitempty"`

	// Hook runs in the SDK process and enables dynamic request/response mutation.
	Hook NetworkHookFunc `json:"-"`
}

NetworkHookRule describes a network interception rule.

type NetworkInterceptionConfig added in v0.1.24 

type NetworkInterceptionConfig struct {
	Rules []NetworkHookRule `json:"rules,omitempty"`
}

NetworkInterceptionConfig configures host-side network interception rules.

type RPCError 

type RPCError struct {
	Code    int
	Message string
}

RPCError represents an error from the Matchlock RPC

func (*RPCError) Error 

func (e *RPCError) Error() string

func (*RPCError) IsExecError 

func (e *RPCError) IsExecError() bool

IsExecError returns true if the error is an execution error

func (*RPCError) IsFileError 

func (e *RPCError) IsFileError() bool

IsFileError returns true if the error is a file operation error

func (*RPCError) IsVMError 

func (e *RPCError) IsVMError() bool

IsVMError returns true if the error is a VM-related error

type SandboxBuilder 

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

SandboxBuilder provides a fluent API for configuring and creating sandboxes.

Usage: 

sandbox := sdk.New("python:3.12-alpine").
	WithCPUs(2).
	WithMemory(1024).
	AllowHost("api.openai.com").
	AddSecret("API_KEY", os.Getenv("API_KEY"), "api.openai.com").
	BlockPrivateIPs()

vmID, err := client.Launch(sandbox)

func New 

func New(image string) *SandboxBuilder

New creates a SandboxBuilder for the given container image.

func (*SandboxBuilder) AddHost added in v0.1.20 

func (b *SandboxBuilder) AddHost(host, ip string) *SandboxBuilder

AddHost injects a static host-to-IP mapping into guest /etc/hosts.

func (*SandboxBuilder) AddSecret 

func (b *SandboxBuilder) AddSecret(name, value string, hosts ...string) *SandboxBuilder

AddSecret registers a secret for MITM injection. The secret is exposed as a placeholder environment variable inside the VM, and the real value is injected into HTTP requests to the specified hosts.

func (*SandboxBuilder) AddSecretWithPlaceholder added in v0.2.8 

func (b *SandboxBuilder) AddSecretWithPlaceholder(name, value, placeholder string, hosts ...string) *SandboxBuilder

AddSecretWithPlaceholder registers a secret with a caller-provided placeholder value exposed inside the VM.

func (*SandboxBuilder) AllowHost 

func (b *SandboxBuilder) AllowHost(hosts ...string) *SandboxBuilder

AllowHost adds one or more hosts to the network allowlist (supports glob patterns).

func (*SandboxBuilder) AllowPrivateIPs added in v0.1.20 

func (b *SandboxBuilder) AllowPrivateIPs() *SandboxBuilder

AllowPrivateIPs explicitly allows access to private IP ranges.

func (*SandboxBuilder) BlockPrivateIPs 

func (b *SandboxBuilder) BlockPrivateIPs() *SandboxBuilder

BlockPrivateIPs blocks access to private IP ranges (10.x, 172.16.x, 192.168.x).

func (*SandboxBuilder) Mount 

func (b *SandboxBuilder) Mount(guestPath string, cfg MountConfig) *SandboxBuilder

Mount adds a VFS mount at the given guest path.

func (*SandboxBuilder) MountHostDir 

func (b *SandboxBuilder) MountHostDir(guestPath, hostPath string) *SandboxBuilder

MountHostDir is a convenience for mounting a host directory into the guest.

func (*SandboxBuilder) MountHostDirReadonly 

func (b *SandboxBuilder) MountHostDirReadonly(guestPath, hostPath string) *SandboxBuilder

MountHostDirReadonly mounts a host directory into the guest as read-only.

func (*SandboxBuilder) MountMemory 

func (b *SandboxBuilder) MountMemory(guestPath string) *SandboxBuilder

MountMemory creates an in-memory filesystem at the given guest path.

func (*SandboxBuilder) MountOverlay 

func (b *SandboxBuilder) MountOverlay(guestPath, hostPath string) *SandboxBuilder

MountOverlay creates an isolated snapshot mount at the given guest path.

func (*SandboxBuilder) Options 

func (b *SandboxBuilder) Options() CreateOptions

Options returns the underlying CreateOptions. Useful when you need to pass the options to Client.Create directly.

func (*SandboxBuilder) UnsetBlockPrivateIPs added in v0.1.20 

func (b *SandboxBuilder) UnsetBlockPrivateIPs() *SandboxBuilder

UnsetBlockPrivateIPs resets private IP blocking to API defaults.

func (*SandboxBuilder) WithBlockPrivateIPs added in v0.1.20 

func (b *SandboxBuilder) WithBlockPrivateIPs(enabled bool) *SandboxBuilder

WithBlockPrivateIPs explicitly configures private IP range blocking.

func (*SandboxBuilder) WithCPUs 

func (b *SandboxBuilder) WithCPUs(cpus float64) *SandboxBuilder

WithCPUs sets the number of vCPUs.

func (*SandboxBuilder) WithDNSServers added in v0.1.7 

func (b *SandboxBuilder) WithDNSServers(servers ...string) *SandboxBuilder

WithDNSServers overrides the default DNS servers (8.8.8.8, 8.8.4.4).

func (*SandboxBuilder) WithDiskSize 

func (b *SandboxBuilder) WithDiskSize(mb int) *SandboxBuilder

WithDiskSize sets disk size in megabytes.

func (*SandboxBuilder) WithEntrypoint added in v0.1.10 

func (b *SandboxBuilder) WithEntrypoint(entrypoint ...string) *SandboxBuilder

WithEntrypoint sets the image entrypoint override.

func (*SandboxBuilder) WithEnv added in v0.1.19 

func (b *SandboxBuilder) WithEnv(name, value string) *SandboxBuilder

WithEnv sets a non-secret environment variable available to commands.

func (*SandboxBuilder) WithEnvMap added in v0.1.19 

func (b *SandboxBuilder) WithEnvMap(env map[string]string) *SandboxBuilder

WithEnvMap merges non-secret environment variables into the sandbox config.

func (*SandboxBuilder) WithHostname added in v0.1.20 

func (b *SandboxBuilder) WithHostname(hostname string) *SandboxBuilder

WithHostname sets the sandbox's hostname

func (*SandboxBuilder) WithImageConfig added in v0.1.10 

func (b *SandboxBuilder) WithImageConfig(cfg *ImageConfig) *SandboxBuilder

WithImageConfig merges the given image configuration into any existing config. Fields set in cfg override existing values; zero-value fields are left unchanged.

func (*SandboxBuilder) WithKernel added in v0.2.6 

func (b *SandboxBuilder) WithKernel(ref string) *SandboxBuilder

WithKernel selects the guest kernel to boot. Supports empty (default), file:///absolute/path, or OCI image refs.

func (*SandboxBuilder) WithMemory 

func (b *SandboxBuilder) WithMemory(mb int) *SandboxBuilder

WithMemory sets memory in megabytes.

func (*SandboxBuilder) WithNetworkInterception added in v0.1.24 

func (b *SandboxBuilder) WithNetworkInterception(cfg ...*NetworkInterceptionConfig) *SandboxBuilder

WithNetworkInterception enables network interception. With no args, it only forces interception for runtime allow-list mutation. With one config arg, it also installs network interception rules.

func (*SandboxBuilder) WithNetworkMTU added in v0.1.20 

func (b *SandboxBuilder) WithNetworkMTU(mtu int) *SandboxBuilder

WithNetworkMTU overrides the guest interface/network stack MTU.

func (*SandboxBuilder) WithNoNetwork added in v0.1.24 

func (b *SandboxBuilder) WithNoNetwork() *SandboxBuilder

WithNoNetwork disables guest network egress entirely (no guest NIC).

func (*SandboxBuilder) WithPortForward added in v0.1.20 

func (b *SandboxBuilder) WithPortForward(localPort, remotePort int) *SandboxBuilder

WithPortForward adds a host-to-guest port mapping.

func (*SandboxBuilder) WithPortForwardAddresses added in v0.1.20 

func (b *SandboxBuilder) WithPortForwardAddresses(addresses ...string) *SandboxBuilder

WithPortForwardAddresses sets host bind addresses for configured mappings.

func (*SandboxBuilder) WithPrivileged added in v0.1.4 

func (b *SandboxBuilder) WithPrivileged() *SandboxBuilder

WithPrivileged enables privileged mode, skipping in-guest security restrictions.

func (*SandboxBuilder) WithTimeout 

func (b *SandboxBuilder) WithTimeout(seconds int) *SandboxBuilder

WithTimeout sets the maximum execution time in seconds.

func (*SandboxBuilder) WithUser added in v0.1.10 

func (b *SandboxBuilder) WithUser(user string) *SandboxBuilder

WithUser sets the user to run commands as (uid, uid:gid, or username).

func (*SandboxBuilder) WithVFSInterception added in v0.1.19 

func (b *SandboxBuilder) WithVFSInterception(cfg *VFSInterceptionConfig) *SandboxBuilder

WithVFSInterception sets host-side VFS interception rules.

func (*SandboxBuilder) WithWorkspace 

func (b *SandboxBuilder) WithWorkspace(path string) *SandboxBuilder

WithWorkspace sets the VFS mount point in the guest.

type Secret 

type Secret struct {
	// Name is the environment variable name (e.g., "ANTHROPIC_API_KEY")
	Name string
	// Value is the actual secret value
	Value string
	// Placeholder overrides the generated in-VM placeholder value when set.
	Placeholder string
	// Hosts is a list of hosts where this secret can be used (supports wildcards)
	Hosts []string
}

Secret defines a secret that will be injected as a placeholder env var and replaced with the real value in HTTP requests to allowed hosts

type VFSActionHookFunc added in v0.1.19 

type VFSActionHookFunc func(ctx context.Context, req VFSActionRequest) VFSHookAction

VFSActionHookFunc decides whether an operation should be allowed or blocked.

type VFSActionRequest added in v0.1.19 

type VFSActionRequest struct {
	Op   VFSHookOp
	Path string
	Size int
	Mode uint32
	UID  int
	GID  int
}

VFSActionRequest is passed to SDK-local allow/block action hooks.

type VFSDangerousHookFunc added in v0.1.19 

type VFSDangerousHookFunc func(ctx context.Context, client *Client, event VFSHookEvent) error

VFSDangerousHookFunc runs with a client handle and can trigger re-entrant hook execution. Use this only when you intentionally need side effects that call back into the sandbox.

type VFSHookAction added in v0.1.19 

type VFSHookAction = string

VFS hook actions. 

const (
	VFSHookActionAllow VFSHookAction = "allow"
	VFSHookActionBlock VFSHookAction = "block"
)

type VFSHookEvent added in v0.1.19 

type VFSHookEvent struct {
	Op   VFSHookOp
	Path string
	Size int64
	Mode uint32
	UID  int
	GID  int
}

VFSHookEvent contains metadata about an intercepted file event.

type VFSHookFunc added in v0.1.19 

type VFSHookFunc func(ctx context.Context, event VFSHookEvent) error

VFSHookFunc runs in the SDK process when a matching after-file-event is observed. Returning an error currently does not fail the triggering VFS operation.

type VFSHookOp added in v0.1.19 

type VFSHookOp = string

VFS hook operations. 

const (
	VFSHookOpStat      VFSHookOp = "stat"
	VFSHookOpReadDir   VFSHookOp = "readdir"
	VFSHookOpOpen      VFSHookOp = "open"
	VFSHookOpCreate    VFSHookOp = "create"
	VFSHookOpMkdir     VFSHookOp = "mkdir"
	VFSHookOpChmod     VFSHookOp = "chmod"
	VFSHookOpRemove    VFSHookOp = "remove"
	VFSHookOpRemoveAll VFSHookOp = "remove_all"
	VFSHookOpRename    VFSHookOp = "rename"
	VFSHookOpSymlink   VFSHookOp = "symlink"
	VFSHookOpReadlink  VFSHookOp = "readlink"
	VFSHookOpRead      VFSHookOp = "read"
	VFSHookOpWrite     VFSHookOp = "write"
	VFSHookOpClose     VFSHookOp = "close"
	VFSHookOpSync      VFSHookOp = "sync"
	VFSHookOpTruncate  VFSHookOp = "truncate"
)

type VFSHookPhase added in v0.1.19 

type VFSHookPhase = string

VFS hook phases. 

const (
	VFSHookPhaseBefore VFSHookPhase = "before"
	VFSHookPhaseAfter  VFSHookPhase = "after"
)

type VFSHookRule added in v0.1.19 

type VFSHookRule struct {
	Name      string        `json:"name,omitempty"`
	Phase     VFSHookPhase  `json:"phase,omitempty"`  // before, after
	Ops       []VFSHookOp   `json:"ops,omitempty"`    // read, write, create, ...
	Path      string        `json:"path,omitempty"`   // filepath-style glob
	Action    VFSHookAction `json:"action,omitempty"` // allow, block
	TimeoutMS int           `json:"timeout_ms,omitempty"`
	// Hook is safe-by-default and does not expose client methods.
	Hook VFSHookFunc `json:"-"`
	// DangerousHook disables recursion suppression and may retrigger itself.
	// Use only when you intentionally want re-entrant callbacks.
	DangerousHook VFSDangerousHookFunc `json:"-"`
	MutateHook    VFSMutateHookFunc    `json:"-"`
	ActionHook    VFSActionHookFunc    `json:"-"`
}

VFSHookRule describes a single interception rule.

type VFSInterceptionConfig added in v0.1.19 

type VFSInterceptionConfig struct {
	EmitEvents bool          `json:"emit_events,omitempty"`
	Rules      []VFSHookRule `json:"rules,omitempty"`
}

VFSInterceptionConfig configures host-side VFS interception rules.

type VFSMutateHookFunc added in v0.1.19 

type VFSMutateHookFunc func(ctx context.Context, req VFSMutateRequest) ([]byte, error)

VFSMutateHookFunc computes replacement bytes for SDK WriteFile calls. This hook runs in the SDK process and currently applies only to write_file RPCs.

type VFSMutateRequest added in v0.1.19 

type VFSMutateRequest struct {
	Path string
	Size int
	Mode uint32
	UID  int
	GID  int
}

VFSMutateRequest is passed to SDK-local mutate hooks before WriteFile.

type VolumeInfo added in v0.1.24 

type VolumeInfo struct {
	Name string
	Size string
	Path string
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.