sdk

package
v0.1.19 Latest Latest
Warning

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

 Go to latest Published: Feb 14, 2026 License: MIT Imports: 16 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").
    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)")
	ErrParseCreateResult = errors.New("parse create result")
	ErrInvalidVFSHook    = errors.New("invalid vfs hook")
	ErrVFSHookBlocked    = errors.New("vfs hook blocked operation")
)

Create / VM errors

View Source 
var (
	ErrParseExecResult       = errors.New("parse exec result")
	ErrParseExecStreamResult = errors.New("parse exec_stream result")
)

Exec errors

View Source 
var (
	ErrParseReadResult = errors.New("parse read result")
	ErrParseListResult = errors.New("parse list result")
)

File operation errors

View Source 
var (
	ErrCloseTimeout = errors.New("close timed out, process killed")
	ErrRemoveVM     = errors.New("matchlock rm")
)

Close / Remove errors

Functions

This section is empty.

Types

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) 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)

Create creates and starts a new sandbox VM

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) 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()).

func (*Client) ListFiles 

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

ListFiles lists files in a directory.

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) WriteFile 

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

WriteFile writes content to a file in the sandbox.

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
	// Privileged skips in-guest security restrictions (seccomp, cap drop, no_new_privs)
	Privileged bool
	// CPUs is the number of vCPUs
	CPUs int
	// 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
	// BlockPrivateIPs blocks access to private IP ranges
	BlockPrivateIPs bool
	// 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 (default: /workspace)
	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
	// ImageConfig holds OCI image metadata (USER, ENTRYPOINT, CMD, WORKDIR, ENV)
	ImageConfig *ImageConfig
}

CreateOptions holds options for creating a sandbox

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
}

ExecResult holds the result of command execution

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, real_fs, overlay
	HostPath string `json:"host_path,omitempty"`
	Readonly bool   `json:"readonly,omitempty"`
}

MountConfig defines a VFS mount

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) 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) AllowHost 

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

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

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 a copy-on-write overlay 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) WithCPUs 

func (b *SandboxBuilder) WithCPUs(cpus int) *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) 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) WithMemory 

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

WithMemory sets memory in megabytes.

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
	// 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.

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.