sdk

package
v0.1.11 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: MIT Imports: 11 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("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
)

Error codes

Variables

This section is empty.

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 kills the process immediately. 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(command string) (*ExecResult, error)

Exec executes a command in the sandbox and returns the buffered result.

func (*Client) ExecStream 

func (c *Client) ExecStream(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(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(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(path string) ([]FileInfo, error)

ListFiles lists files in a directory

func (*Client) ReadFile 

func (c *Client) ReadFile(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(path string, content []byte) error

WriteFile writes content to a file in the sandbox

func (*Client) WriteFileMode 

func (c *Client) WriteFileMode(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
	// 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
	// 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) 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) 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

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.