Guides / Go / API reference

Go API reference

Every export of github.com/kosa8ai/kosa8-go v0.1.2, package kosa8. Signatures are copied from the source, and the list of names on this page was checked against go doc -all. Paths are the daemon's native API; … stands for /kosa8/v1/sandboxes/{sandbox}.

Conventions

• Every method that talks to the daemon takes a context.Context first. Its deadline or cancellation ends the HTTP request (not a process already running in the sandbox).
• call ...Call is an optional trailing kosa8.Call{Approval: id}; only the first is used. Methods that take an options struct carry Approval in it instead. The approval is sent as the X-Kosa8-Approval header.
• Info is map[string]any: the daemon's JSON object, unchanged, with JSON numbers as float64.
• Every error returned by this package is a *kosa8.Error, except a cancelled (not timed-out) context, which comes back as context.Canceled, and failures from a custom CheckpointStore or the checkpoint file, which come back as they are.

Client

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

func New(o Options) (*Client, error)
func (c *Client) Endpoint() Endpoint

New resolves the endpoint (see ResolveEndpoint), checks Actor, builds the HTTP client and picks the checkpoint store. It sends nothing. It fails with a KindUsage error for a refused KOSA8_HOST or host, or an actor other than human, agent or tool. A *Client is safe for concurrent use by multiple goroutines. Endpoint reports where requests go.

Options

type Options struct {
	SocketPath string // default ~/.kosa8/run/kosa8.sock
	Host       string // a remote worker; default $KOSA8_HOST
	Token      string // bearer token for Host; default $KOSA8_TOKEN when Host came from the env
	Insecure   bool   // allow plain http to a non-loopback worker
	Actor      string // human | agent | tool (default tool)
	AgentToken string // default $KOSA8_AGENT_TOKEN
	Headers    map[string]string
	HTTPClient *http.Client // overrides the transport entirely
	// Checkpoints is where checkpoint stacks live. Default: the CLI's own
	// ~/.kosa8/checkpoints.json, so `kosa8 rewind` and this SDK share them.
	Checkpoints CheckpointStore
	Getenv      func(string) string // for tests; default os.Getenv
}

Daemon

Sandboxes

Running code

Run, Exec and Attach fail with KindStream when the stream ends with an error frame, with a frame that cannot be decoded, or with no final frame; with KindTimeout when RunOptions.Timeout or the context's deadline passes. In both cases the error's Stdout/Stderr and the returned ExecResult hold the output so far. A non-zero exit code is not an error. opts may be nil.

Snapshots, fork, explore

Explore fails with KindUsage for fewer than two variants, when the fork returned fewer branches than variants, and when Keep names no branch (then it returns the result with every branch kept). A branch that fails to run is recorded in its Error field rather than failing the call; connection-level failures are retried up to four times, 0.5 s, 1 s and 1.5 s apart.

Checkpoints

Checkpoint errors: KindCheckpoint for an invalid sandbox name (empty, ., .., containing / or \, or starting with a dot), no checkpoints to rewind to, or a to that matches nothing. If the restore step of Rewind fails, the error is KindCheckpoint wrapping the daemon's error (Err), with the message restore failed and NAME no longer exists (it was deleted to free its name for the restore): … — the checkpoint is intact; recover with RestoreSnapshot("ID", RestoreOptions{Name: "NAME"}); by then the sandbox has been deleted and the snapshot is intact. If the delete step fails, its error is returned unchanged and nothing has changed.

Handle

func (c *Client) Sandbox(id string) *Sandbox

Returns a handle bound to one sandbox. It sends nothing and does not check that the sandbox exists.

Sandbox

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

There is no ExecFrames, StartInteractive, WriteStdin, Attach, RestoreSnapshot or DeleteSnapshot on the handle; call them on the client with s.ID.

Option types

Call

type Call struct{ Approval string }

Per-request options: a signed approval id, sent as X-Kosa8-Approval (trimmed; omitted when empty).

CreateOptions

type CreateOptions struct {
	Name   string
	CPUs   int
	MemMB  int
	DiskGB int
	Mounts []string // host:guest[:ro]; host must be absolute
	Egress string   // deny | any | fakenet | allow:host,host
	// EgressAllow limits the network to these hosts (sets Egress to allow:…).
	EgressAllow []string
	// Capture records the sandbox's network traffic as pcap segments under
	// Capture.Path, a file on the host (pcapng). nil records nothing.
	Capture  *CaptureOptions
	Labels   map[string]string
	Broker   any // the credential-broker config, passed through
	Approval string
}

// CaptureOptions turn on packet capture for a sandbox (daemon 0.9.36 writes one pcapng file at Path).
type CaptureOptions struct {
	Path     string // host file the capture is written to (required)
	MaxBytes int64  // per segment; 0 is the daemon's default
	MaxFiles int    // segments kept; 0 is the daemon's default
}

Other option types

type DeleteOptions struct {
	Wipe            bool // overwrite the disks, not just unlink them
	KeepCheckpoints bool // keep this sandbox's checkpoint snapshots
	Approval        string
}

type RunOptions struct {
	Env      []string // KEY=VALUE
	OnStdout func([]byte)
	OnStderr func([]byte)
	OnStatus func([]byte) // pull/progress lines
	Timeout  time.Duration
	Approval string
}

type InteractiveOptions struct {
	Env      []string
	TTY      bool
	Approval string
}

type SnapshotOptions struct {
	ID       string // default: the daemon picks one
	Encrypt  bool
	Approval string
}

type RestoreOptions struct {
	Name          string
	Label         string
	AllowTampered bool
	Approval      string
}

type SnapshotDeleteOptions struct {
	Wipe, Force bool
	Approval    string
}

type ForkOptions struct {
	Prefix   string
	Label    string
	Approval string
}

type ExploreOptions struct {
	Image    string        // default alpine:latest
	KeepAll  bool          // keep every branch
	Keep     string        // keep this branch instead of the fastest success
	Timeout  time.Duration // per branch; default 120s
	Prefix   string
	NoPull   bool // the image is already in the sandbox
	Approval string
}

Result types

type Info = map[string]any

type ExecResult struct {
	ExitCode    int
	StdoutBytes []byte
	StderrBytes []byte
}
func (r ExecResult) Stdout() string
func (r ExecResult) Stderr() string
func (r ExecResult) OK() bool // ExitCode == 0

type ForkResult struct {
	Forks    []Info `json:"forks"`
	Snapshot any    `json:"snapshot"`
	ForkMS   int64  `json:"fork_ms"`
	Count    int    `json:"count"`
}

type ExploreBranch struct {
	Name       string
	Variant    string
	Exit       int
	Output     string
	Error      string // set when the branch could not run
	DurationMS int64
}

type ExploreResult struct {
	Parent   string
	Branches []ExploreBranch
	Winner   string // "" when no branch succeeded
	Removed  int
}

type Checkpoint struct {
	ID      string    `json:"id"`
	Sandbox string    `json:"sandbox"`
	Label   string    `json:"label"`
	Auto    bool      `json:"auto,omitempty"`
	Created time.Time `json:"created"`
}

type CheckpointResult struct {
	Checkpoint Checkpoint
	Evicted    []string
	Snapshot   Info
}

type RewindResult struct {
	Sandbox    any
	Checkpoint Checkpoint
	Dropped    []string
	RestoreMS  any
}

Checkpoint stores

const MaxCheckpointsPerSandbox = 10

type CheckpointStore interface {
	Load() (map[string][]Checkpoint, error)
	// Update runs fn on the stacks and saves what it leaves, serialised against other updates.
	Update(fn func(map[string][]Checkpoint) error) error
}

type FileCheckpointStore struct {
	Path string
	// contains filtered or unexported fields
}
func NewFileCheckpointStore(path string) *FileCheckpointStore
func (f *FileCheckpointStore) Load() (map[string][]Checkpoint, error)
func (f *FileCheckpointStore) Update(fn func(map[string][]Checkpoint) error) error

type MemoryCheckpointStore struct {
	// contains filtered or unexported fields
}
func (m *MemoryCheckpointStore) Load() (map[string][]Checkpoint, error)
func (m *MemoryCheckpointStore) Update(fn func(map[string][]Checkpoint) error) error

Endpoint, frames and constants

const Version = "0.1.2"

const (
	ApprovalHeader   = "X-Kosa8-Approval"
	ActorHeader      = "X-Kosa8-Actor"
	AgentTokenHeader = "X-Kosa8-Agent-Token"
)

func DefaultSocketPath() string // $HOME/.kosa8/run/kosa8.sock

type Endpoint struct {
	Unix  string   // socket path, when local
	URL   *url.URL // remote worker, when not
	Token string
}
func (e Endpoint) Target() string // "unix://PATH" or "SCHEME://HOST"

func ResolveEndpoint(host, socketPath, token string, insecure bool, getenv func(string) string) (Endpoint, error)

type Frame struct {
	Stream string `json:"stream,omitempty"` // stdout | stderr | status
	Data   []byte `json:"data,omitempty"`
	Done   bool   `json:"done,omitempty"`
	OK     bool   `json:"ok,omitempty"`
	Error  string `json:"error,omitempty"`
	Exit   *int   `json:"exit,omitempty"`
	ID     string `json:"id,omitempty"`
}

ResolveEndpoint follows the CLI's KOSA8_HOST rules. It sends nothing.

• The address is host if non-empty, else KOSA8_HOST from getenv (nil means os.Getenv), trimmed of spaces and trailing slashes.
• Empty: the unix socket socketPath, or DefaultSocketPath().
• unix:///path: that socket. tcp://h:p and a bare h:p: http://h:p. http:// and https://: as given (the scheme's case is ignored, and a path is kept as a prefix). Any other scheme, or no host name, is a KindUsage error.
• Plain http to a host other than localhost, ::1 or 127.* is a KindUsage error unless insecure or KOSA8_INSECURE=1.
• token is kept for a URL endpoint; when empty and the address came from KOSA8_HOST, KOSA8_TOKEN is used. A unix endpoint carries no token.

Frame is one NDJSON frame of a run, exec or attach stream, with Data decoded from base64. Output frames have Stream and Data; the last frame has Done, and either OK and Exit, or Error.

Errors

type Error struct {
	Kind          Kind
	Message       string
	Status        int    // HTTP status, when the daemon answered
	DaemonMessage string // the daemon's "error" text, verbatim
	Remediation   string // the daemon's "remediation": what to do about it
	Method, Path  string
	Body          any            // the decoded response body
	Approval      map[string]any // set when Kind == KindApprovalRequired: the daemon's refusal
	Stdout        string         // KindStream: output produced before the error
	Stderr        string
	Err           error // the underlying cause, if any
}
func (e *Error) Error() string        // Message
func (e *Error) Unwrap() error        // Err
func (e *Error) Is(target error) bool

func AsError(err error) (*Error, bool)

type Kind string

const (
	KindConnection       Kind = "connection"        // daemon unreachable
	KindAPI              Kind = "api"               // any other HTTP error
	KindBadRequest       Kind = "bad_request"       // 400
	KindAuth             Kind = "auth"              // 401
	KindPolicy           Kind = "policy"            // 403
	KindApprovalRequired Kind = "approval_required" // 403 needing a signed approval
	KindNotFound         Kind = "not_found"         // 404
	KindConflict         Kind = "conflict"          // 409
	KindUnsupported      Kind = "unsupported"       // 501
	KindStream           Kind = "stream"            // a stream ended with an error frame
	KindCheckpoint       Kind = "checkpoint"        // client-side checkpoint bookkeeping
	KindTimeout          Kind = "timeout"
	KindUsage            Kind = "usage" // bad arguments
)

var (
	ErrConnection       = &Error{Kind: KindConnection}
	ErrAPI              = &Error{Kind: KindAPI}
	ErrBadRequest       = &Error{Kind: KindBadRequest}
	ErrAuth             = &Error{Kind: KindAuth}
	ErrPolicy           = &Error{Kind: KindPolicy}
	ErrApprovalRequired = &Error{Kind: KindApprovalRequired}
	ErrNotFound         = &Error{Kind: KindNotFound}
	ErrConflict         = &Error{Kind: KindConflict}
	ErrUnsupported      = &Error{Kind: KindUnsupported}
	ErrStream           = &Error{Kind: KindStream}
	ErrCheckpoint       = &Error{Kind: KindCheckpoint}
	ErrTimeout          = &Error{Kind: KindTimeout}
	ErrUsage            = &Error{Kind: KindUsage}
)

Is matches a target *Error with an empty Message (a sentinel, or &kosa8.Error{Kind: k}) by Kind. Two extra rules: ErrPolicy also matches KindApprovalRequired, and ErrAPI matches every HTTP kind (api, bad_request, auth, policy, approval_required, not_found, conflict, unsupported). ErrUsage (new in v0.1.1) matches KindUsage. AsError is errors.As into a *Error. When each kind occurs, with real messages: Go errors and troubleshooting.