client

package
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2026 License: MIT Imports: 12 Imported by: 2

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNetworkUnsupportedPlatform = errors.New("network unsupported on this platform")
	ErrNetworkInvalidConfig       = errors.New("invalid network config")
)
View Source 
var ErrMountInvalidConfig = errors.New("invalid mount config")
View Source 
var (
	// ErrNativeUnavailable means govm is running with the non-native stub binding.
	ErrNativeUnavailable = errors.New("govm native bridge unavailable: rebuild with -tags govm_native and bundled native libs")
)

Functions

func ListOfflineImages 

func ListOfflineImages() ([]string, error)

ListOfflineImages returns embedded offline image names.

func ValidateMounts added in v0.1.1 

func ValidateMounts(mounts []Mount) error

func ValidateNetworkConfig 

func ValidateNetworkConfig(cfg *NetworkConfig) error

Types

type Box 

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

Box is a handle to one sandbox VM.

func (*Box) Close 

func (b *Box) Close()

Close only frees the handle; it does not remove the underlying box.

func (*Box) Exec 

func (b *Box) Exec(command string, opts *ExecOptions) (*ExecResult, error)

func (*Box) ExecStream added in v0.1.3 

func (b *Box) ExecStream(command string, opts *ExecOptions, cb ExecStreamCallbacks) (*ExecResult, error)

func (*Box) ID 

func (b *Box) ID() string

func (*Box) Info 

func (b *Box) Info() (BoxInfo, error)

func (*Box) Name 

func (b *Box) Name() string

func (*Box) Start 

func (b *Box) Start() error

func (*Box) Stop 

func (b *Box) Stop() error

type BoxInfo 

type BoxInfo struct {
	ID        string    `json:"id"`
	Name      string    `json:"name,omitempty"`
	Image     string    `json:"image"`
	State     string    `json:"state"`
	CreatedAt time.Time `json:"created_at"`
}

BoxInfo contains metadata and state of a box.

type BoxOptions 

type BoxOptions struct {
	Image string `json:"image"`
	// LocalBundlePath points to a local OCI image layout directory.
	// When set, it takes precedence over Image.
	LocalBundlePath string `json:"local_bundle_path,omitempty"`
	// RootfsPath is kept for backward compatibility and aliases LocalBundlePath.
	// Deprecated: use LocalBundlePath.
	RootfsPath string `json:"rootfs_path,omitempty"`
	// OfflineImage references an embedded offline image bundle shipped in this repo.
	// Runtime.CreateBox will extract it and fill RootfsPath automatically.
	OfflineImage string            `json:"offline_image,omitempty"`
	CPUs         int               `json:"cpus,omitempty"`
	MemoryMB     int               `json:"memory_mb,omitempty"`
	Env          map[string]string `json:"env,omitempty"`
	WorkingDir   string            `json:"working_dir,omitempty"`
	Mounts       []Mount           `json:"mounts,omitempty"`
	Network      *NetworkConfig    `json:"network,omitempty"`
}

BoxOptions configures a new box.

type CIDRRule 

type CIDRRule struct {
	CIDR      string   `json:"cidr"`
	Protocol  Protocol `json:"protocol,omitempty"`
	PortStart uint16   `json:"port_start,omitempty"`
	PortEnd   uint16   `json:"port_end,omitempty"`
}

type DNSConfig 

type DNSConfig struct {
	Servers       []string `json:"servers,omitempty"`
	SearchDomains []string `json:"search_domains,omitempty"`
	BlockPrivate  bool     `json:"block_private,omitempty"`
}

type DomainRule 

type DomainRule struct {
	Domain   string   `json:"domain"`
	Port     uint16   `json:"port,omitempty"`
	Protocol Protocol `json:"protocol,omitempty"`
}

type ExecOptions 

type ExecOptions struct {
	Args       []string
	Env        map[string]string
	TTY        bool
	User       string
	Timeout    time.Duration
	WorkingDir string
}

ExecOptions controls execution behavior for a command.

type ExecResult 

type ExecResult struct {
	ExitCode int
	Stdout   []string
	Stderr   []string
}

ExecResult is the final result of command execution.

type ExecStreamCallbacks added in v0.1.3 

type ExecStreamCallbacks struct {
	OnStdout func(string)
	OnStderr func(string)
}

ExecStreamCallbacks receives incremental stdout/stderr from guest command execution.

type Mount added in v0.1.1 

type Mount struct {
	HostPath  string `json:"host_path,omitempty"`
	GuestPath string `json:"guest_path,omitempty"`
	ReadOnly  bool   `json:"read_only,omitempty"`
}

type NetworkConfig 

type NetworkConfig struct {
	Enabled            bool           `json:"enabled"`
	Mode               NetworkMode    `json:"mode,omitempty"`
	Policy             *NetworkPolicy `json:"policy,omitempty"`
	PortForwards       []PortForward  `json:"port_forwards,omitempty"`
	IsolateFromHostLAN bool           `json:"isolate_from_host_lan,omitempty"`
}

func BalancedNetworkProfile 

func BalancedNetworkProfile() *NetworkConfig

func OpenNetworkProfile 

func OpenNetworkProfile() *NetworkConfig

func StrictNetworkProfile 

func StrictNetworkProfile() *NetworkConfig

type NetworkMode 

type NetworkMode string
const (
	NetworkDisabled NetworkMode = "disabled"
	NetworkNAT      NetworkMode = "nat"
	NetworkBridged  NetworkMode = "bridged"
)

type NetworkPolicy 

type NetworkPolicy struct {
	Mode        PolicyMode     `json:"mode,omitempty"`
	AllowCIDR   []CIDRRule     `json:"allow_cidr,omitempty"`
	DenyCIDR    []CIDRRule     `json:"deny_cidr,omitempty"`
	AllowDomain []DomainRule   `json:"allow_domain,omitempty"`
	DenyDomain  []DomainRule   `json:"deny_domain,omitempty"`
	DNS         *DNSConfig     `json:"dns,omitempty"`
	Proxy       *ProxyConfig   `json:"proxy,omitempty"`
	Limits      *TrafficLimits `json:"limits,omitempty"`
}

type OfflineImageMetadata 

type OfflineImageMetadata struct {
	Name      string
	Archive   string
	SHA256    string
	SizeBytes int64
}

func ListOfflineImageMetadata 

func ListOfflineImageMetadata() ([]OfflineImageMetadata, error)

ListOfflineImageMetadata returns metadata for embedded offline image bundles.

type PolicyMode 

type PolicyMode string
const (
	PolicyBlockAll PolicyMode = "block_all"
	PolicyAllowAll PolicyMode = "allow_all"
)

type PortForward 

type PortForward struct {
	HostIP    string   `json:"host_ip,omitempty"`
	HostPort  uint16   `json:"host_port"`
	GuestPort uint16   `json:"guest_port"`
	Protocol  Protocol `json:"protocol,omitempty"`
}

type Protocol 

type Protocol string
const (
	ProtoTCP Protocol = "tcp"
	ProtoUDP Protocol = "udp"
	ProtoAny Protocol = "any"
)

type ProxyConfig 

type ProxyConfig struct {
	HTTPProxy  string   `json:"http_proxy,omitempty"`
	HTTPSProxy string   `json:"https_proxy,omitempty"`
	NoProxy    []string `json:"no_proxy,omitempty"`
	Enforce    bool     `json:"enforce,omitempty"`
}

type Runtime 

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

Runtime is the high-level client entry point.

func NewRuntime 

func NewRuntime(opts *RuntimeOptions) (*Runtime, error)

NewRuntime creates a new runtime.

func (*Runtime) Close 

func (r *Runtime) Close()

Close releases runtime resources.

func (*Runtime) CreateBox 

func (r *Runtime) CreateBox(ctx context.Context, name string, opts BoxOptions) (*Box, error)

CreateBox creates and returns a box handle.

func (*Runtime) GetBox 

func (r *Runtime) GetBox(ctx context.Context, idOrName string) (*Box, error)

GetBox returns nil,nil when the box does not exist.

func (*Runtime) ListBoxes 

func (r *Runtime) ListBoxes(ctx context.Context) ([]BoxInfo, error)

ListBoxes returns all boxes in this runtime.

func (*Runtime) RemoveBox 

func (r *Runtime) RemoveBox(ctx context.Context, idOrName string, force bool) error

RemoveBox removes a box by id or name.

type RuntimeNetworkDefaults 

type RuntimeNetworkDefaults struct {
	Profile string         `json:"profile,omitempty"`
	Config  *NetworkConfig `json:"config,omitempty"`
}

type RuntimeOptions 

type RuntimeOptions struct {
	HomeDir         string
	ImageRegistries []string
	NetworkDefaults *RuntimeNetworkDefaults
}

RuntimeOptions configures Runtime creation.

type TrafficLimits 

type TrafficLimits struct {
	MaxEgressBytesPerSec  int64 `json:"max_egress_bps,omitempty"`
	MaxIngressBytesPerSec int64 `json:"max_ingress_bps,omitempty"`
	MaxConnections        int   `json:"max_connections,omitempty"`
}

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.