run9

package module
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2026 License: MIT Imports: 30 Imported by: 0

README

run9-sdk-go

run9-sdk-go is the public Go SDK for the run9 control-plane API.

The module path is github.com/sys9-ai/run9-sdk-go. The package name is run9.

Documentation

If the public API changes, README, doc comments, and examples are updated in the same change.

Install

go get github.com/sys9-ai/run9-sdk-go@latest

The SDK uses semantic version tags. For reproducible builds, pin one released tag in your go.mod instead of an unpublished commit.

Quick Start

package main

import (
	"context"
	"log"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		log.Fatal(err)
	}

	project := client.WithProject("default")
	boxes, err := project.ListBoxes(context.Background(), run9.ListBoxesRequest{})
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("loaded %d boxes", len(boxes))
}

Calling Model

This SDK is intentionally opinionated. It uses one stable calling style across the package:

  1. Create one client from endpoint and credentials.
  2. Use the base client for global APIs such as account, org, shared snaps, and project discovery.
  3. Use client.WithProject(...) before calling any project-scoped API.
  4. Keep simple identity inputs positional, and use request structs for optional filters or mutable payloads.
  5. Use typed streaming helpers instead of raw NDJSON bodies or websocket frames.

The SDK models the public control-plane contract. It does not include local config persistence, terminal rendering, shell completion, or local cursor persistence.

Common Workflows

Load the current authenticated identity:

identity, err := client.WhoAmI(ctx)

List accessible projects:

projects, err := client.ListProjects(ctx)

Create one box in a project:

project := client.WithProject("sandbox")

box, err := project.CreateBox(ctx, run9.CreateBoxRequest{
	BoxID:          "devbox",
	DesiredShape:   "2c4g",
	SourceImageRef: "public.ecr.aws/docker/library/alpine:3.20",
})
if err == nil {
	log.Printf("browse box files at %s", box.FileAccessURL)
}

Resolve a reusable read-only filesystem and stream files without transfer jobs:

files, err := project.BoxFileSystem(ctx, "devbox")
if err != nil {
	return err
}

page, err := files.ReadDir(ctx, "/work/site", run9.ReadDirRequest{Limit: 100})
if err != nil {
	return err
}

reader, err := files.Open(ctx, "/work/site/index.html", run9.OpenFileOptions{})
if err != nil {
	return err
}
defer reader.Close()
_, err = io.Copy(os.Stdout, reader)

Use project.SnapFileSystem(ctx, snapID) for the same operations on a snap. A detached snap reads its immutable settled generation; an attached snap resolves to its owning box view. Resolve FileSystem once and reuse it for concurrent Open, Stat, and paginated ReadDir calls so ordinary file reads do not return to the control plane.

Run one foreground exec and stream its output:

result, err := project.RunExec(ctx, "devbox", run9.ExecRequest{
	Command: []string{"/bin/sh", "-lc", "echo hello"},
}, run9.ExecOutputWriters{
	Stdout: os.Stdout,
	Stderr: os.Stderr,
})

result tells you whether the exec exited, was cancelled, or failed. When you need direct event control, StartExecStream(...) and ReadEvent() are still available.

Run one foreground exec and wait for the final merged transcript:

capture, err := project.RunExecCapture(ctx, "devbox", run9.ExecRequest{
	Command: []string{"/bin/sh", "-lc", "echo hello"},
})
if err != nil {
	return err
}
if capture.TranscriptUnavailableReason != "" {
	return fmt.Errorf("exec finished but its final transcript is unavailable: %s", capture.TranscriptUnavailableReason)
}
fmt.Printf("exit=%d transcript=%s", *capture.Terminal.ExitCode, capture.Transcript)

RunExecCapture(...) is the stable completion helper. It uses the live foreground stream to start the command, then falls back to durable exec truth plus log-download when the stream transport breaks near terminal. The returned transcript always follows the merged log-download view, so it does not preserve stdout and stderr as separate streams. If the exec finished but the transcript archive is unavailable, the helper still returns the terminal result and reports the transcript problem through TranscriptUnavailableReason.

Start one background exec and follow its output with an internal cursor:

execView, err := project.StartBackgroundExec(ctx, "devbox", run9.ExecRequest{
	Command:        []string{"/bin/sh", "-lc", "long task"},
	StdinEnabled:   true,
	IdempotencyKey: "daemon-generation-42",
})
if err != nil {
	return err
}

follower := project.FollowBackgroundExec(execView.ExecID)
result, err := follower.Pump(ctx, 2*time.Second, run9.ExecOutputWriters{
	Stdout: os.Stdout,
	Stderr: os.Stderr,
})

Persist one stable IdempotencyKey for each logical daemon generation and reuse it when retrying after an uncertain response. The same key and request return the original exec; changing the request while reusing the key returns a conflict. If omitted, the SDK generates a new key for that StartBackgroundExec call.

result.NextCursor is still exposed for explicit replay use cases, but callers that only want to keep tailing can let the follower manage it.

If you want one merged transcript in event order, call Read(...) and then WriteMergedOutput(...):

result, err := follower.Read(ctx, 2*time.Second)
if err != nil {
	return err
}
if err := result.WriteMergedOutput(os.Stdout, os.Stderr); err != nil {
	return err
}

API Surface

Global APIs live on the base client:

  • account identity and SSH keys
  • org metadata, members, invitations, API keys, and org hosts
  • project list, inspect, and create
  • shared snap catalog list, inspect, publish, and delete

Project-scoped APIs require WithProject(...):

  • boxes
  • snaps
  • execs
  • file archive upload and download
  • reusable read-only box and snap filesystems
  • project members
  • project and box secrets
  • create-from-shared-snap flows

If a project-scoped method is called without WithProject(...), the SDK returns an explicit error instead of guessing a default project.

Errors

Non-2xx responses are returned as *run9.Error.

if err != nil {
	var apiErr *run9.Error
	if errors.As(err, &apiErr) {
		log.Printf("run9 request failed: status=%d message=%q", apiErr.StatusCode, apiErr.Message)
	}
}

The SDK avoids silent fallbacks. Missing credentials, invalid endpoints, and missing project scope are returned as direct errors.

Compatibility

Before v1.0.0, breaking API cleanup is allowed when it materially improves clarity or ergonomics. Every exported API change must land together with:

  • updated doc comments
  • updated README examples
  • passing go test ./...

Documentation

Overview

Package run9 provides the public Go SDK for the run9 control-plane API.

The package follows one consistent calling model:

  • Create one Client with NewClient by binding the API endpoint and API key once.
  • Use the base client for account, organization, shared-snap, and project-discovery APIs.
  • Use Client.WithProject to derive a project-scoped client for boxes, snaps, execs, archives, and secrets.
  • Pass request structs when a call has optional filters or mutable payload.
  • Use high-level helpers such as Client.RunExec, Client.RunExecCapture, and Client.FollowBackgroundExec when you want terminal results plus live output or one merged transcript.
  • Drop down to typed stream helpers such as ExecStream and ExecAttachSocket only when you need direct event control.

The module path is github.com/sys9-ai/run9-sdk-go, while the package name is run9: 

client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
	AK: "ak-...",
	SK: "sk-...",
})
if err != nil {
	return
}

project := client.WithProject("default")
_, _ = project.ListBoxes(context.Background(), run9.ListBoxesRequest{})

Non-2xx responses are returned as *Error. When the control plane returns a structured error message, it is exposed through Error.Message.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIKeyView 

type APIKeyView struct {
	APIKeyID          string    `json:"api_key_id"`
	OrgID             string    `json:"org_id"`
	UserID            string    `json:"user_id"`
	OwnerPrimaryEmail string    `json:"owner_primary_email"`
	OwnerDisplayName  string    `json:"owner_display_name,omitempty"`
	Description       string    `json:"description,omitempty"`
	AK                string    `json:"ak"`
	DisplayPrefix     string    `json:"display_prefix"`
	DisplaySuffix     string    `json:"display_suffix"`
	CreatedAt         time.Time `json:"created_at"`
	ExpiresAt         time.Time `json:"expires_at,omitempty"`
	NoExpire          bool      `json:"no_expire"`
}

APIKeyView describes one API key without secret key material.

type BackgroundExecFollower added in v0.2.0 

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

BackgroundExecFollower tracks one background exec cursor and hides repeated pull-output polling.

func (*BackgroundExecFollower) Cursor added in v0.2.0 

func (f *BackgroundExecFollower) Cursor() string

Cursor returns the current replay cursor.

func (*BackgroundExecFollower) Pump added in v0.2.0 

func (f *BackgroundExecFollower) Pump(ctx context.Context, wait time.Duration, writers ExecOutputWriters) (BackgroundExecPullOutput, error)

Pump reads one meaningful output window and writes stdout to Stdout and stderr plus notices to Stderr.

func (*BackgroundExecFollower) Read added in v0.2.0 

func (f *BackgroundExecFollower) Read(ctx context.Context, wait time.Duration) (BackgroundExecPullOutput, error)

Read waits for the next meaningful output window.

When wait is positive, Read skips empty and started-only polls while the exec stays active.

func (*BackgroundExecFollower) Reset added in v0.2.0 

func (f *BackgroundExecFollower) Reset()

Reset clears the current replay cursor so the next read starts from the beginning once.

func (*BackgroundExecFollower) SetCursor added in v0.2.0 

func (f *BackgroundExecFollower) SetCursor(cursor string)

SetCursor overwrites the current replay cursor.

type BackgroundExecOutputEvent added in v0.2.0 

type BackgroundExecOutputEvent struct {
	// Seq is the durable event sequence number for incremental replay.
	Seq uint64
	// Type identifies whether this event is stdout, stderr, gap, truncated, or terminal.
	Type BackgroundExecOutputEventType
	// Data carries stdout or stderr bytes on output events.
	Data []byte
	// GapBytes reports how many bytes were omitted on gap events.
	GapBytes uint64
	// ExitCode is set on exit events.
	ExitCode *int
	// Reason is set on cancelled and error events.
	Reason string
}

BackgroundExecOutputEvent describes one decoded background exec output event.

type BackgroundExecOutputEventType added in v0.2.0 

type BackgroundExecOutputEventType string

BackgroundExecOutputEventType identifies one event decoded from a background exec output window. 

const (
	// BackgroundExecOutputEventStarted reports the durable exec start marker.
	BackgroundExecOutputEventStarted BackgroundExecOutputEventType = "started"
	// BackgroundExecOutputEventStdout reports one stdout chunk.
	BackgroundExecOutputEventStdout BackgroundExecOutputEventType = "stdout"
	// BackgroundExecOutputEventStderr reports one stderr chunk.
	BackgroundExecOutputEventStderr BackgroundExecOutputEventType = "stderr"
	// BackgroundExecOutputEventGap reports that older bytes were omitted around the current cursor.
	BackgroundExecOutputEventGap BackgroundExecOutputEventType = "gap"
	// BackgroundExecOutputEventTruncated reports that the service truncated retained output at its hard limit.
	BackgroundExecOutputEventTruncated BackgroundExecOutputEventType = "truncated"
	// BackgroundExecOutputEventExit reports a terminal process exit.
	BackgroundExecOutputEventExit BackgroundExecOutputEventType = "exit"
	// BackgroundExecOutputEventCancelled reports a terminal cancellation.
	BackgroundExecOutputEventCancelled BackgroundExecOutputEventType = "cancelled"
	// BackgroundExecOutputEventError reports a terminal runtime or control-plane failure.
	BackgroundExecOutputEventError BackgroundExecOutputEventType = "error"
)

type BackgroundExecPullOutput 

type BackgroundExecPullOutput struct {
	// Events carries the decoded output and terminal events returned by this poll.
	Events []BackgroundExecOutputEvent
	// NextCursor is the cursor to use on the next incremental poll.
	NextCursor string
	// State is the current durable exec state.
	State string
	// ExitCode is set after terminal exit when the exec produced one.
	ExitCode *int
	// Reason carries the durable terminal reason when one is available.
	Reason string
	// IdleDeadlineAt is the current idle lease deadline when the control plane reports it.
	IdleDeadlineAt *time.Time
}

BackgroundExecPullOutput describes one decoded background exec output window.

func (BackgroundExecPullOutput) TerminalResult added in v0.2.0 

func (r BackgroundExecPullOutput) TerminalResult() *ExecTerminalResult

TerminalResult returns the terminal outcome carried by this output window when one is available.

func (BackgroundExecPullOutput) WriteMergedOutput added in v0.2.0 

func (r BackgroundExecPullOutput) WriteMergedOutput(output io.Writer, notices io.Writer) error

WriteMergedOutput writes stdout and stderr chunks to output in event order and writes gap or truncation notices to notices.

Example 
package main

import (
	"io"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	result := run9.BackgroundExecPullOutput{
		Events: []run9.BackgroundExecOutputEvent{
			{Type: run9.BackgroundExecOutputEventStdout, Data: []byte("hello\n")},
			{Type: run9.BackgroundExecOutputEventStderr, Data: []byte("warn\n")},
		},
	}

	if err := result.WriteMergedOutput(io.Discard, io.Discard); err != nil {
		panic(err)
	}
}

func (BackgroundExecPullOutput) WriteOutput added in v0.2.0 

func (r BackgroundExecPullOutput) WriteOutput(writers ExecOutputWriters) error

WriteOutput writes stdout events to Stdout, stderr events to Stderr, and gap or truncation notices to Stderr.

type BoxNetworkMode 

type BoxNetworkMode string

BoxNetworkMode represents the requested networking mode for a box. 

const (
	// BoxNetworkModeNormal requests the default non-managed network path.
	BoxNetworkModeNormal BoxNetworkMode = "normal"
	// BoxNetworkModeManaged requests the managed network path.
	BoxNetworkModeManaged BoxNetworkMode = "managed"
)

Box network modes accepted by box create and update APIs.

type BoxState 

type BoxState string

BoxState represents the current box state.

type BoxView 

type BoxView struct {
	BoxID                     string            `json:"box_id"`
	OrgID                     string            `json:"org_id"`
	ProjectID                 string            `json:"project_id"`
	Creator                   string            `json:"creator"`
	CreatedAt                 time.Time         `json:"created_at"`
	LastUsedAt                time.Time         `json:"last_used_at"`
	Description               string            `json:"description,omitempty"`
	Labels                    map[string]string `json:"labels,omitempty"`
	State                     BoxState          `json:"state"`
	Reason                    string            `json:"reason,omitempty"`
	BoxSnapID                 string            `json:"box_snap_id"`
	FileAccessURL             string            `json:"file_access_url,omitempty"`
	DesiredShape              string            `json:"desired_shape"`
	NetworkMode               BoxNetworkMode    `json:"network_mode"`
	CurrentHostID             string            `json:"current_host_id,omitempty"`
	CurrentRuntimeShape       string            `json:"current_runtime_shape,omitempty"`
	CurrentRuntimeNetworkMode BoxNetworkMode    `json:"current_runtime_network_mode,omitempty"`
	PendingShapeChange        bool              `json:"pending_shape_change"`
	PendingNetworkModeChange  bool              `json:"pending_network_mode_change"`
}

BoxView describes one box. FileAccessURL is its stable read-only filesystem capability URL.

type Client 

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

Client is the public run9 control-plane HTTP client.

func NewClient 

func NewClient(endpoint string, creds Credentials) (*Client, error)

NewClient creates one authenticated run9 control-plane HTTP client rooted at the given endpoint.

Example 
package main

import (
	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	projectClient := client.WithProject("default")
	_, _ = client, projectClient
}

func (*Client) BoxFileSystem added in v0.5.0 

func (c *Client) BoxFileSystem(ctx context.Context, boxID string) (*FileSystem, error)

BoxFileSystem resolves one Box filesystem capability.

Example 
package main

import (
	"context"
	"io"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	files, err := client.WithProject("sandbox").BoxFileSystem(context.Background(), "devbox")
	if err != nil {
		panic(err)
	}
	reader, err := files.Open(context.Background(), "/work/site/index.html", run9.OpenFileOptions{})
	if err != nil {
		panic(err)
	}
	defer reader.Close()
	_, _ = io.Copy(io.Discard, reader)
}

func (*Client) CreateAPIKey 

func (c *Client) CreateAPIKey(ctx context.Context, req CreateAPIKeyRequest) (CreatedAPIKeyView, error)

CreateAPIKey creates one API key in the current organization.

func (*Client) CreateBox 

func (c *Client) CreateBox(ctx context.Context, req CreateBoxRequest) (BoxView, error)

CreateBox creates one project-scoped box.

func (*Client) CreateBoxFromSharedSnap 

func (c *Client) CreateBoxFromSharedSnap(ctx context.Context, name string, req CreateBoxFromSharedSnapRequest) (BoxView, error)

CreateBoxFromSharedSnap creates a box from one shared snap.

func (*Client) CreateBoxSecret 

func (c *Client) CreateBoxSecret(ctx context.Context, boxID string, req CreateProjectSecretRequest) (ProjectSecretView, error)

CreateBoxSecret creates one box-scoped secret.

func (*Client) CreateInvitation 

func (c *Client) CreateInvitation(ctx context.Context, orgID string, req CreateInvitationRequest) (InvitationView, error)

CreateInvitation creates one invitation in an organization.

func (*Client) CreateProject 

func (c *Client) CreateProject(ctx context.Context, req CreateProjectRequest) (ProjectView, error)

CreateProject creates one project.

func (*Client) CreateProjectSecret 

func (c *Client) CreateProjectSecret(ctx context.Context, req CreateProjectSecretRequest) (ProjectSecretView, error)

CreateProjectSecret creates one project-scoped secret.

func (*Client) CreateSSHKey 

func (c *Client) CreateSSHKey(ctx context.Context, req CreateSSHKeyRequest) (SSHKeyView, error)

CreateSSHKey registers one SSH public key on the caller's account.

func (*Client) CreateSnapFromSharedSnap 

func (c *Client) CreateSnapFromSharedSnap(ctx context.Context, name string, req CreateSnapFromSharedSnapRequest) (SnapView, error)

CreateSnapFromSharedSnap creates a snap from one shared snap.

func (*Client) DeleteBox 

func (c *Client) DeleteBox(ctx context.Context, boxID string) (BoxView, error)

DeleteBox deletes one box.

func (*Client) DeleteBoxSecret 

func (c *Client) DeleteBoxSecret(ctx context.Context, boxID string, secretID string) error

DeleteBoxSecret deletes one box-scoped secret.

func (*Client) DeleteOrg 

func (c *Client) DeleteOrg(ctx context.Context, orgID string) (DeleteOrgResult, error)

DeleteOrg deletes one organization.

func (*Client) DeleteOrgMember 

func (c *Client) DeleteOrgMember(ctx context.Context, orgID string, userID string) error

DeleteOrgMember removes one member from an organization.

func (*Client) DeleteProject 

func (c *Client) DeleteProject(ctx context.Context) (DeleteProjectResult, error)

DeleteProject deletes the current project.

func (*Client) DeleteProjectMember 

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

DeleteProjectMember removes one member from the current project.

func (*Client) DeleteProjectSecret 

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

DeleteProjectSecret deletes one project-scoped secret.

func (*Client) DeleteSSHKey 

func (c *Client) DeleteSSHKey(ctx context.Context, sshKeyID string) (SSHKeyView, error)

DeleteSSHKey removes one SSH key from the caller's account.

func (*Client) DeleteSharedSnap 

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

DeleteSharedSnap deletes one shared snap name and all of its versions.

func (*Client) DeleteSharedSnapVersion 

func (c *Client) DeleteSharedSnapVersion(ctx context.Context, name string, version int) error

DeleteSharedSnapVersion deletes one shared snap version.

func (*Client) DeleteSnap 

func (c *Client) DeleteSnap(ctx context.Context, snapID string) (SnapView, error)

DeleteSnap deletes one snap.

func (*Client) DownloadArchive 

func (c *Client) DownloadArchive(ctx context.Context, boxID string, boxAbsPath string) (io.ReadCloser, error)

DownloadArchive downloads one box path as a tar archive.

func (*Client) DownloadExecLog 

func (c *Client) DownloadExecLog(ctx context.Context, execID string) (io.ReadCloser, error)

DownloadExecLog downloads the stored log for one exec.

func (*Client) FollowBackgroundExec added in v0.2.0 

func (c *Client) FollowBackgroundExec(execID string) *BackgroundExecFollower

FollowBackgroundExec returns a cursor-tracking follower for one background exec.

Example 
package main

import (
	"context"
	"io"
	"time"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	project := client.WithProject("sandbox")
	follower := project.FollowBackgroundExec("exec-123")
	result, err := follower.Pump(context.Background(), 2*time.Second, run9.ExecOutputWriters{
		Stdout: io.Discard,
		Stderr: io.Discard,
	})
	if err != nil {
		panic(err)
	}

	_ = result.TerminalResult()
}

func (*Client) ForkSnap 

func (c *Client) ForkSnap(ctx context.Context, snapID string) (SnapView, error)

ForkSnap creates a writable child snap from an existing snap.

func (*Client) GetBox 

func (c *Client) GetBox(ctx context.Context, boxID string) (BoxView, error)

GetBox loads one project-scoped box by ID.

func (*Client) GetExec 

func (c *Client) GetExec(ctx context.Context, execID string) (ExecView, error)

GetExec loads one exec by ID from the current project.

func (*Client) GetOrgHosts 

func (c *Client) GetOrgHosts(ctx context.Context) (OrgHostsView, error)

GetOrgHosts loads runtime hosts assigned to the current organization.

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, projectCID string) (ProjectView, error)

GetProject loads one project by CID.

func (*Client) GetSharedSnap 

func (c *Client) GetSharedSnap(ctx context.Context, name string) (SharedSnapDetailView, error)

GetSharedSnap loads one shared snap and its versions.

func (*Client) GetSnap 

func (c *Client) GetSnap(ctx context.Context, snapID string) (SnapView, error)

GetSnap loads one project-scoped snap by ID.

func (*Client) GetSnapTree 

func (c *Client) GetSnapTree(ctx context.Context, snapID string) (SnapTreeView, error)

GetSnapTree loads the ancestry tree for one snap.

func (*Client) ImportSnap 

func (c *Client) ImportSnap(ctx context.Context, req ImportSnapRequest) (SnapView, error)

ImportSnap imports a snap from an image reference into the current project.

func (*Client) KillBackgroundExec 

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

KillBackgroundExec requests termination of one background exec.

func (*Client) ListAPIKeys 

func (c *Client) ListAPIKeys(ctx context.Context) ([]APIKeyView, error)

ListAPIKeys lists API keys visible to the caller in the current organization.

func (*Client) ListBoxSecrets 

func (c *Client) ListBoxSecrets(ctx context.Context, boxID string) ([]ProjectSecretView, error)

ListBoxSecrets lists box-scoped secrets for one box.

func (*Client) ListBoxes 

func (c *Client) ListBoxes(ctx context.Context, req ListBoxesRequest) ([]BoxView, error)

ListBoxes lists project-scoped boxes with optional creator, label, and state filters.

func (*Client) ListExecs 

func (c *Client) ListExecs(ctx context.Context, req ListExecsRequest) (ListExecsResult, error)

ListExecs lists execs in the current project with optional filters.

func (*Client) ListInvitations 

func (c *Client) ListInvitations(ctx context.Context, orgID string) ([]InvitationView, error)

ListInvitations lists invitations in one organization.

func (*Client) ListOrgMembers 

func (c *Client) ListOrgMembers(ctx context.Context, orgID string) ([]MembershipView, error)

ListOrgMembers lists members in one organization.

func (*Client) ListProjectMembers 

func (c *Client) ListProjectMembers(ctx context.Context) ([]ProjectMembershipView, error)

ListProjectMembers lists members in the current project.

func (*Client) ListProjectSecrets 

func (c *Client) ListProjectSecrets(ctx context.Context) ([]ProjectSecretView, error)

ListProjectSecrets lists project-scoped secrets for the current project.

func (*Client) ListProjects 

func (c *Client) ListProjects(ctx context.Context) ([]ProjectView, error)

ListProjects lists projects visible to the caller.

func (*Client) ListSSHKeys 

func (c *Client) ListSSHKeys(ctx context.Context) ([]SSHKeyView, error)

ListSSHKeys lists SSH keys registered on the caller's account.

func (*Client) ListSharedSnaps 

func (c *Client) ListSharedSnaps(ctx context.Context) ([]SharedSnapLineView, error)

ListSharedSnaps lists shared snaps visible to the caller.

func (*Client) ListSnaps 

func (c *Client) ListSnaps(ctx context.Context, req ListSnapsRequest) ([]SnapView, error)

ListSnaps lists project-scoped snaps with an optional attached filter.

func (*Client) OpenExecAttach 

func (c *Client) OpenExecAttach(ctx context.Context, attachURL string) (*ExecAttachSocket, error)

OpenExecAttach dials one exec attach websocket returned by the control plane.

func (*Client) PublishSharedSnap 

func (c *Client) PublishSharedSnap(ctx context.Context, req PublishSharedSnapRequest) (SharedSnapVersionView, error)

PublishSharedSnap publishes one snap into the shared snap catalog.

func (*Client) PullBackgroundExecOutput 

func (c *Client) PullBackgroundExecOutput(ctx context.Context, execID string, req PullBackgroundExecOutputRequest) (BackgroundExecPullOutput, error)

PullBackgroundExecOutput polls output and state transitions for one background exec.

func (*Client) RevokeAPIKey 

func (c *Client) RevokeAPIKey(ctx context.Context, apiKeyID string) (APIKeyView, error)

RevokeAPIKey revokes one API key in the current organization.

func (*Client) RevokeInvitation 

func (c *Client) RevokeInvitation(ctx context.Context, orgID string, invitationID string) (DeleteInvitationResult, error)

RevokeInvitation revokes one organization invitation.

func (*Client) RunExec added in v0.2.0 

func (c *Client) RunExec(ctx context.Context, boxID string, req ExecRequest, writers ExecOutputWriters) (ExecTerminalResult, error)

RunExec starts one inline foreground exec, pumps its output, and returns the terminal result.

Example 
package main

import (
	"context"
	"io"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	project := client.WithProject("sandbox")
	_, err = project.RunExec(context.Background(), "devbox", run9.ExecRequest{
		Command: []string{"/bin/sh", "-lc", "echo hello"},
	}, run9.ExecOutputWriters{
		Stdout: io.Discard,
		Stderr: io.Discard,
	})
	if err != nil {
		panic(err)
	}

	_ = project
}

func (*Client) RunExecCapture added in v0.3.0 

func (c *Client) RunExecCapture(ctx context.Context, boxID string, req ExecRequest) (ExecCapture, error)

RunExecCapture starts one foreground exec, waits for a terminal result, and loads the final merged log snapshot.

The helper uses the normal foreground live stream to start the command. If that transport breaks after the exec has been accepted, it polls the durable exec record and still returns a terminal result when one becomes visible. It does not change foreground exec disconnect semantics, and the returned Transcript intentionally follows the merged log-download view instead of preserving stdout and stderr as separate streams.

Example 
package main

import (
	"context"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	project := client.WithProject("sandbox")
	capture, err := project.RunExecCapture(context.Background(), "devbox", run9.ExecRequest{
		Command: []string{"/bin/sh", "-lc", "echo hello"},
	})
	if err != nil {
		panic(err)
	}

	_, _ = capture.Transcript, capture.Terminal
}

func (*Client) SnapFileSystem added in v0.5.0 

func (c *Client) SnapFileSystem(ctx context.Context, snapID string) (*FileSystem, error)

SnapFileSystem resolves one Snap filesystem capability. Detached snaps use their immutable read view; attached snaps resolve to their owning Box view.

func (*Client) StartBackgroundExec 

func (c *Client) StartBackgroundExec(ctx context.Context, boxID string, req ExecRequest) (ExecView, error)

StartBackgroundExec starts one background exec in a box.

Example 
package main

import (
	"context"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	project := client.WithProject("sandbox")
	_, err = project.StartBackgroundExec(context.Background(), "devbox", run9.ExecRequest{
		Command:        []string{"/bin/sh", "-lc", "long task"},
		IdempotencyKey: "daemon-generation-42",
	})
	if err != nil {
		panic(err)
	}
}

func (*Client) StartExec 

func (c *Client) StartExec(ctx context.Context, boxID string, req ExecRequest) (ExecView, error)

StartExec starts one foreground exec and returns its initial view.

func (*Client) StartExecStream 

func (c *Client) StartExecStream(ctx context.Context, boxID string, req ExecRequest) (*ExecStream, error)

StartExecStream starts a streaming exec and returns one event reader.

func (*Client) StopBox 

func (c *Client) StopBox(ctx context.Context, boxID string) (BoxView, error)

StopBox requests a graceful stop for one box.

func (*Client) UpdateAccount 

func (c *Client) UpdateAccount(ctx context.Context, req UpdateMeRequest) (MeView, error)

UpdateAccount updates mutable fields on the caller's user account.

func (*Client) UpdateBox 

func (c *Client) UpdateBox(ctx context.Context, boxID string, req UpdateBoxRequest) (BoxView, error)

UpdateBox updates mutable fields on one box.

func (*Client) UpdateBoxSecret 

func (c *Client) UpdateBoxSecret(ctx context.Context, boxID string, secretID string, req UpdateProjectSecretRequest) (ProjectSecretView, error)

UpdateBoxSecret updates one box-scoped secret.

func (*Client) UpdateOrg 

func (c *Client) UpdateOrg(ctx context.Context, orgID string, req UpdateOrgRequest) (OrgView, error)

UpdateOrg updates mutable fields on one organization.

func (*Client) UpdateOrgMember 

func (c *Client) UpdateOrgMember(ctx context.Context, orgID string, userID string, req UpdateMembershipRequest) (MembershipView, error)

UpdateOrgMember updates one organization member.

func (*Client) UpdateProject 

func (c *Client) UpdateProject(ctx context.Context, req UpdateProjectRequest) (ProjectView, error)

UpdateProject updates mutable fields on the current project.

func (*Client) UpdateProjectMember 

func (c *Client) UpdateProjectMember(ctx context.Context, userID string, req UpdateProjectMembershipRequest) (ProjectMembershipView, error)

UpdateProjectMember updates one member in the current project.

func (*Client) UpdateProjectSecret 

func (c *Client) UpdateProjectSecret(ctx context.Context, secretID string, req UpdateProjectSecretRequest) (ProjectSecretView, error)

UpdateProjectSecret updates one project-scoped secret.

func (*Client) UploadArchive 

func (c *Client) UploadArchive(ctx context.Context, boxID string, boxAbsPath string, source io.Reader) (RuntimeRequestView, error)

UploadArchive uploads one tar archive into a box path.

func (*Client) WhoAmI 

func (c *Client) WhoAmI(ctx context.Context) (CurrentOrgIdentityView, error)

WhoAmI loads the current authenticated user and organization identity.

func (*Client) WithProject 

func (c *Client) WithProject(projectCID string) *Client

WithProject returns a shallow client clone pinned to one project CID.

Example 
package main

import (
	"context"

	run9 "github.com/sys9-ai/run9-sdk-go"
)

func main() {
	client, err := run9.NewClient("https://api.run.sys9.ai", run9.Credentials{
		AK: "ak-...",
		SK: "sk-...",
	})
	if err != nil {
		panic(err)
	}

	project := client.WithProject("sandbox")
	_, _ = project.ListBoxes(context.Background(), run9.ListBoxesRequest{})
}

func (*Client) WriteBackgroundExecStdin 

func (c *Client) WriteBackgroundExecStdin(ctx context.Context, execID string, req WriteBackgroundExecStdinRequest) (*time.Time, error)

WriteBackgroundExecStdin writes stdin bytes into one background exec.

type CreateAPIKeyRequest 

type CreateAPIKeyRequest struct {
	// Description is optional operator-facing API key text.
	Description string `json:"description,omitempty"`
	// ExpiresAt requests one explicit expiry time when non-nil.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	// NoExpire requests a non-expiring API key.
	NoExpire bool `json:"no_expire"`
}

CreateAPIKeyRequest creates one API key for the current organization.

type CreateBoxFromSharedSnapRequest 

type CreateBoxFromSharedSnapRequest struct {
	// Version selects one published version. When nil, the latest version is used.
	Version *int `json:"version,omitempty"`
	// BoxID requests one specific box identifier. When empty, the control plane generates one.
	BoxID string `json:"box_id,omitempty"`
	// DesiredShape requests the compute shape for the box.
	DesiredShape string `json:"desired_shape,omitempty"`
	// NetworkMode requests the durable network mode for the box.
	NetworkMode BoxNetworkMode `json:"network_mode,omitempty"`
	// Description is optional free-form box text.
	Description string `json:"description,omitempty"`
	// Labels sets durable box labels.
	Labels map[string]string `json:"labels,omitempty"`
}

CreateBoxFromSharedSnapRequest creates a box from a published shared snap.

type CreateBoxRequest 

type CreateBoxRequest struct {
	// BoxID requests one specific box identifier. When empty, the control plane generates one.
	BoxID string `json:"box_id,omitempty"`
	// DesiredShape requests the compute shape for the box.
	DesiredShape string `json:"desired_shape,omitempty"`
	// NetworkMode requests the durable network mode for the box.
	NetworkMode BoxNetworkMode `json:"network_mode,omitempty"`
	// Description is optional free-form box text.
	Description string `json:"description,omitempty"`
	// Labels sets durable box labels.
	Labels map[string]string `json:"labels,omitempty"`
	// SourceSnapID creates the box from one existing snap when non-empty.
	SourceSnapID string `json:"source_snap_id,omitempty"`
	// SourceImageRef imports directly from one image reference when non-empty.
	SourceImageRef string `json:"source_image_ref,omitempty"`
}

CreateBoxRequest creates a new box from an image or snap.

type CreateInvitationRequest 

type CreateInvitationRequest struct {
	// InviteeEmail is the target email address.
	InviteeEmail string `json:"invitee_email"`
	// Role is the organization role to grant on acceptance.
	Role MembershipRole `json:"role"`
}

CreateInvitationRequest invites one user into an organization.

type CreateProjectRequest 

type CreateProjectRequest struct {
	// DisplayName is the human-readable project name.
	DisplayName string `json:"display_name"`
	// Description is optional free-form project text.
	Description string `json:"description,omitempty"`
}

CreateProjectRequest creates a new project.

type CreateProjectSecretRequest 

type CreateProjectSecretRequest struct {
	// Name is an optional human-readable secret name.
	Name string `json:"name,omitempty"`
	// Value is the raw secret value to store.
	Value string `json:"value"`
	// Placeholder is the literal marker that managed egress will replace.
	Placeholder string `json:"placeholder"`
	// AllowedHosts lists the destination hosts where placeholder substitution is allowed.
	AllowedHosts []string `json:"allowed_hosts"`
	// InjectHeaderName selects which HTTP header names are eligible for substitution.
	InjectHeaderName string `json:"inject_header_name"`
}

CreateProjectSecretRequest creates a new project or box secret.

type CreateSSHKeyRequest 

type CreateSSHKeyRequest struct {
	// Label is the human-readable SSH key label.
	Label string `json:"label"`
	// PublicKey is the authorized_keys-formatted SSH public key.
	PublicKey string `json:"public_key"`
}

CreateSSHKeyRequest creates one account SSH key.

type CreateSnapFromSharedSnapRequest 

type CreateSnapFromSharedSnapRequest struct {
	// Version selects one published version. When nil, the latest version is used.
	Version *int `json:"version,omitempty"`
}

CreateSnapFromSharedSnapRequest creates a new snap from a shared snap version.

type CreatedAPIKeyView 

type CreatedAPIKeyView struct {
	APIKeyID          string    `json:"api_key_id"`
	OrgID             string    `json:"org_id"`
	UserID            string    `json:"user_id"`
	OwnerPrimaryEmail string    `json:"owner_primary_email"`
	OwnerDisplayName  string    `json:"owner_display_name,omitempty"`
	Description       string    `json:"description,omitempty"`
	AK                string    `json:"ak"`
	SK                string    `json:"sk"`
	DisplayPrefix     string    `json:"display_prefix"`
	DisplaySuffix     string    `json:"display_suffix"`
	CreatedAt         time.Time `json:"created_at"`
	ExpiresAt         time.Time `json:"expires_at,omitempty"`
	NoExpire          bool      `json:"no_expire"`
}

CreatedAPIKeyView describes a newly created API key, including its secret key.

type Credentials 

type Credentials struct {
	// AK is the access-key identifier.
	AK string
	// SK is the secret-key value paired with AK.
	SK string
}

Credentials are the org-scoped API key credentials used by run9 clients.

type CurrentOrgIdentityView 

type CurrentOrgIdentityView struct {
	User     MeView  `json:"user"`
	Org      OrgView `json:"org"`
	AuthKind string  `json:"auth_kind"`
}

CurrentOrgIdentityView describes the current authenticated user and org.

type CurrentSubscriptionView 

type CurrentSubscriptionView struct {
	Tier      string    `json:"tier"`
	StartDate time.Time `json:"start_date,omitempty"`
	EndDate   time.Time `json:"end_date,omitempty"`
}

CurrentSubscriptionView describes the caller's current subscription snapshot.

type DeleteInvitationResult 

type DeleteInvitationResult struct {
	InvitationID string `json:"invitation_id"`
	Status       string `json:"status"`
}

DeleteInvitationResult describes the accepted result of revoking an invitation.

type DeleteOrgResult 

type DeleteOrgResult struct {
	OrgID  string `json:"org_id"`
	Status string `json:"status"`
}

DeleteOrgResult describes the accepted result of deleting an organization.

type DeleteProjectResult 

type DeleteProjectResult struct {
	ProjectID string `json:"project_id"`
	Status    string `json:"status"`
}

DeleteProjectResult describes the accepted result of deleting a project.

type Error 

type Error struct {
	// StatusCode is the HTTP status returned by the control plane.
	StatusCode int
	// Message is the structured control-plane error message when one is available.
	Message string
}

Error represents one run9 control-plane request failure.

func (*Error) Error 

func (e *Error) Error() string

Error returns the control-plane message when present.

type ExecAttachInput 

type ExecAttachInput struct {
	// Type identifies the input frame kind. Supported values are stdin, close_stdin, and resize.
	Type string `json:"type"`
	// Data carries stdin bytes when Type is stdin.
	Data []byte `json:"data,omitempty"`
	// Rows carries the new terminal height when Type is resize.
	Rows uint32 `json:"rows,omitempty"`
	// Cols carries the new terminal width when Type is resize.
	Cols uint32 `json:"cols,omitempty"`
}

ExecAttachInput describes one input message sent over exec attach.

type ExecAttachSocket 

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

ExecAttachSocket wraps one exec attach websocket connection.

func (*ExecAttachSocket) Close 

func (s *ExecAttachSocket) Close() error

Close closes the underlying websocket connection.

func (*ExecAttachSocket) CloseStdin added in v0.2.0 

func (s *ExecAttachSocket) CloseStdin() error

CloseStdin closes remote stdin for the attached exec session.

func (*ExecAttachSocket) Pump added in v0.2.0 

func (s *ExecAttachSocket) Pump(ctx context.Context, writers ExecOutputWriters) (ExecTerminalResult, error)

Pump writes stdout and stderr events to the given writers until the attached stream reaches a terminal event or ctx ends.

func (*ExecAttachSocket) ReadEvent 

func (s *ExecAttachSocket) ReadEvent() (ExecStreamEvent, error)

ReadEvent reads the next exec stream event from the websocket.

func (*ExecAttachSocket) ResizeTTY added in v0.2.0 

func (s *ExecAttachSocket) ResizeTTY(rows uint32, cols uint32) error

ResizeTTY sends one terminal resize event for the attached exec session.

func (*ExecAttachSocket) WriteInput 

func (s *ExecAttachSocket) WriteInput(input ExecAttachInput) error

WriteInput writes one exec attach input frame to the websocket.

func (*ExecAttachSocket) WriteStdin added in v0.2.0 

func (s *ExecAttachSocket) WriteStdin(data []byte) error

WriteStdin writes one stdin chunk into the attached exec session.

type ExecCapture added in v0.3.0 

type ExecCapture struct {
	// ExecID is the durable foreground exec identifier.
	ExecID string
	// Terminal is the normalized terminal outcome.
	Terminal ExecTerminalResult
	// Transcript is the final merged transcript when log-download is available.
	Transcript []byte
	// TranscriptUnavailableReason explains why Transcript could not be loaded after the exec reached a terminal state.
	TranscriptUnavailableReason string
}

ExecCapture describes one foreground exec after the SDK has observed a terminal result.

Transcript is the final merged log-download snapshot when it is available. It follows the control-plane log-download contract, so stdout and stderr are already merged and the body may include omission or truncation markers for bounded retention.

type ExecOutputWriters added in v0.2.0 

type ExecOutputWriters struct {
	Stdout io.Writer
	Stderr io.Writer
}

ExecOutputWriters selects where exec stdout, stderr, and output notices are written.

Nil writers are treated as io.Discard.

type ExecRequest 

type ExecRequest struct {
	// IdempotencyKey identifies one logical background exec creation. Reusing the key
	// with the same request returns the existing exec; reusing it with a different
	// request fails. StartBackgroundExec generates a key when this field is empty.
	IdempotencyKey string `json:"-"`
	// DeadlineAt requests a hard deadline. When nil, the target exec API applies its default.
	DeadlineAt *time.Time `json:"deadline_at,omitempty"`
	// Command is the argv array executed in the target box.
	Command []string `json:"command"`
	// EnvOverrides replaces or adds environment variables for this exec.
	EnvOverrides map[string]string `json:"env_overrides,omitempty"`
	// User selects the target user account inside the box when non-empty.
	User string `json:"user,omitempty"`
	// Workdir selects the target working directory when non-empty.
	Workdir string `json:"workdir,omitempty"`
	// StdinEnabled keeps stdin available for this exec when true.
	StdinEnabled bool `json:"stdin_enabled,omitempty"`
	// TTY requests one PTY-backed exec session.
	TTY bool `json:"tty,omitempty"`
	// TTYSize provides the initial PTY size when TTY is true.
	TTYSize *TTYSize `json:"tty_size,omitempty"`
}

ExecRequest starts one foreground or background exec in a box.

type ExecStream 

type ExecStream struct {
	// ExecID is the durable exec identifier assigned by the control plane.
	ExecID string
	// contains filtered or unexported fields
}

ExecStream reads one inline foreground exec event stream.

func (*ExecStream) Close 

func (s *ExecStream) Close() error

Close closes the underlying stream body.

func (*ExecStream) Pump added in v0.2.0 

func (s *ExecStream) Pump(ctx context.Context, writers ExecOutputWriters) (ExecTerminalResult, error)

Pump writes stdout and stderr events to the given writers until the stream reaches a terminal event or ctx ends.

func (*ExecStream) ReadEvent 

func (s *ExecStream) ReadEvent() (ExecStreamEvent, error)

ReadEvent reads the next inline foreground exec event.

type ExecStreamEvent 

type ExecStreamEvent struct {
	// Type identifies the event kind. Common values include started, keepalive, stdout,
	// stderr, exit, error, and cancelled.
	Type string `json:"type"`
	// ExecID carries the durable exec identifier on events that include it.
	ExecID string `json:"exec_id,omitempty"`
	// Data carries stdout or stderr bytes for stream output events.
	Data []byte `json:"data,omitempty"`
	// ExitCode is set on terminal exit events.
	ExitCode int32 `json:"exit_code,omitempty"`
	// FailureReason is set when the stream terminates with an error event.
	FailureReason string `json:"failure_reason,omitempty"`
	// CancelReason is set when the stream terminates with a cancelled event.
	CancelReason string `json:"cancel_reason,omitempty"`
}

ExecStreamEvent describes one event emitted by exec streaming APIs.

type ExecTerminalResult added in v0.2.0 

type ExecTerminalResult struct {
	// Status identifies whether the exec exited, was cancelled, or failed.
	Status ExecTerminalStatus
	// ExitCode is set when the terminal outcome includes a process exit code.
	ExitCode *int
	// Reason carries the terminal cancellation or failure reason when one is available.
	Reason string
}

ExecTerminalResult describes the terminal outcome of one foreground, attached, or background exec stream.

type ExecTerminalStatus added in v0.2.0 

type ExecTerminalStatus string

ExecTerminalStatus identifies how one exec stream reached a terminal state. 

const (
	// ExecTerminalStatusExited reports a normal process exit with an exit code.
	ExecTerminalStatusExited ExecTerminalStatus = "exited"
	// ExecTerminalStatusCancelled reports a terminal cancellation.
	ExecTerminalStatusCancelled ExecTerminalStatus = "cancelled"
	// ExecTerminalStatusError reports a terminal runtime or control-plane failure.
	ExecTerminalStatusError ExecTerminalStatus = "error"
)

type ExecView 

type ExecView struct {
	ExecID         string         `json:"exec_id"`
	BoxID          string         `json:"box_id"`
	OrgID          string         `json:"org_id"`
	ProjectID      string         `json:"project_id"`
	Creator        string         `json:"creator"`
	AcceptedAt     time.Time      `json:"accepted_at"`
	Source         string         `json:"source"`
	CommandSummary string         `json:"command_summary"`
	ShapeSnapshot  string         `json:"shape_snapshot"`
	Mode           string         `json:"mode,omitempty"`
	State          string         `json:"state"`
	ExitCode       *int           `json:"exit_code,omitempty"`
	OutputSummary  string         `json:"output_summary,omitempty"`
	Reason         string         `json:"reason,omitempty"`
	HardDeadlineAt *time.Time     `json:"hard_deadline_at,omitempty"`
	IdleDeadlineAt *time.Time     `json:"idle_deadline_at,omitempty"`
	StdinEnabled   bool           `json:"stdin_enabled,omitempty"`
	AttachURL      string         `json:"attach_url,omitempty"`
	Diagnostics    map[string]any `json:"diagnostics,omitempty"`
}

ExecView describes one exec request and its current state.

func (ExecView) TerminalResult added in v0.3.0 

func (v ExecView) TerminalResult() *ExecTerminalResult

TerminalResult returns the normalized terminal outcome when this exec view is terminal.

type FileEntry added in v0.5.0 

type FileEntry struct {
	Name    string    `json:"name"`
	Type    FileType  `json:"type"`
	Size    int64     `json:"size"`
	ModTime time.Time `json:"mod_time"`
	ETag    string    `json:"etag,omitempty"`
}

FileEntry describes one child returned by FileSystem.ReadDir.

type FileInfo added in v0.5.0 

type FileInfo struct {
	Path        string    `json:"path"`
	Type        FileType  `json:"type"`
	Size        int64     `json:"size"`
	ModTime     time.Time `json:"mod_time,omitempty"`
	ETag        string    `json:"etag,omitempty"`
	ContentType string    `json:"content_type,omitempty"`
}

FileInfo describes one path returned by FileSystem.Stat.

type FileReader added in v0.5.0 

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

FileReader streams one file response and exposes its metadata.

func (*FileReader) Close added in v0.5.0 

func (reader *FileReader) Close() error

Close releases the underlying HTTP response body.

func (*FileReader) Info added in v0.5.0 

func (reader *FileReader) Info() FileInfo

Info returns metadata from the file response headers.

func (*FileReader) Read added in v0.5.0 

func (reader *FileReader) Read(data []byte) (int, error)

Read reads file content from the gateway response.

type FileSystem added in v0.5.0 

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

FileSystem is a reusable read-only Box or Snap filesystem capability. It reuses the parent Client's HTTP transport and does not contact the control plane again after resolution.

func (*FileSystem) Open added in v0.5.0 

func (fileSystem *FileSystem) Open(ctx context.Context, filePath string, options OpenFileOptions) (*FileReader, error)

Open starts a streamed read of one regular file.

func (*FileSystem) ReadDir added in v0.5.0 

func (fileSystem *FileSystem) ReadDir(ctx context.Context, directoryPath string, request ReadDirRequest) (ReadDirPage, error)

ReadDir loads one bounded, name-ordered directory page.

func (*FileSystem) Stat added in v0.5.0 

func (fileSystem *FileSystem) Stat(ctx context.Context, filePath string) (FileInfo, error)

Stat loads metadata for one file or directory without reading its content.

type FileType added in v0.5.0 

type FileType string

FileType identifies the kind of one filesystem entry. 

const (
	// FileTypeFile identifies a regular file.
	FileTypeFile FileType = "file"
	// FileTypeDirectory identifies a directory.
	FileTypeDirectory FileType = "directory"
	// FileTypeSymlink identifies a symbolic link in a directory listing.
	FileTypeSymlink FileType = "symlink"
)

type HostIssue 

type HostIssue struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

HostIssue describes one issue reported for a runtime host.

type HostView 

type HostView struct {
	HostID string `json:"host_id"`

	HostClass      string `json:"host_class,omitempty"`
	LifecycleState string `json:"lifecycle_state,omitempty"`
	InstanceID     string `json:"instance_id,omitempty"`
	OwnerOrgID     string `json:"owner_org_id,omitempty"`

	MachineID                 string `json:"machine_id,omitempty"`
	BootID                    string `json:"boot_id,omitempty"`
	Hostname                  string `json:"hostname,omitempty"`
	VmaVersion                string `json:"vma_version,omitempty"`
	ChVersion                 string `json:"ch_version,omitempty"`
	RtVersion                 string `json:"rt_version,omitempty"`
	ForegroundRelayConfigured bool   `json:"foreground_relay_configured,omitempty"`

	Connected       bool      `json:"connected"`
	Ready           bool      `json:"ready"`
	LastHeartbeatAt time.Time `json:"last_heartbeat_at,omitempty"`

	ActiveBoxes                                uint32 `json:"active_boxes"`
	ActiveExecs                                uint32 `json:"active_execs"`
	ActiveTransfers                            uint32 `json:"active_transfers"`
	ActiveBackgroundOwnerExecs                 uint32 `json:"active_background_owner_execs"`
	VMAServiceRestartPreservesBackgroundOwners bool   `json:"vma_service_restart_preserves_background_owners"`

	PlanningReservedCPUMillis   uint32 `json:"planning_reserved_cpu_millis"`
	PlanningReservedMemoryBytes uint64 `json:"planning_reserved_memory_bytes"`

	CPUTotalCores              float64 `json:"cpu_total_cores"`
	MemoryTotalBytes           uint64  `json:"memory_total_bytes"`
	CPUUsedCores               float64 `json:"cpu_used_cores"`
	MemoryUsedBytes            uint64  `json:"memory_used_bytes"`
	RuntimeReservedCPUMillis   uint32  `json:"runtime_reserved_cpu_millis"`
	RuntimeReservedMemoryBytes uint64  `json:"runtime_reserved_memory_bytes"`

	LastIssueSummary string      `json:"last_issue_summary,omitempty"`
	Issues           []HostIssue `json:"issues,omitempty"`
}

HostView describes one runtime host assigned to an organization.

type ImportSnapRequest 

type ImportSnapRequest struct {
	// ImageRef is the OCI-style image reference to import.
	ImageRef string `json:"image_ref"`
}

ImportSnapRequest imports a snap from an image reference.

type InvitationState 

type InvitationState string

InvitationState represents one invitation lifecycle state.

type InvitationView 

type InvitationView struct {
	InvitationID string          `json:"invitation_id"`
	OrgID        string          `json:"org_id"`
	InviteeEmail string          `json:"invitee_email"`
	Role         MembershipRole  `json:"role"`
	InvitedBy    string          `json:"invited_by"`
	State        InvitationState `json:"state"`
	ExpiresAt    time.Time       `json:"expires_at"`
	AcceptedBy   string          `json:"accepted_by,omitempty"`
	CreatedAt    time.Time       `json:"created_at"`
	UpdatedAt    time.Time       `json:"updated_at"`
}

InvitationView describes one organization invitation.

type ListBoxesRequest 

type ListBoxesRequest struct {
	// Creator filters by the creator identifier.
	Creator string
	// Label filters by one label selector supported by the control plane.
	Label string
	// State filters by the current box state.
	State BoxState
}

ListBoxesRequest describes optional filters for ListBoxes.

type ListExecsRequest 

type ListExecsRequest struct {
	BoxID          string
	State          string
	Creator        string
	AcceptedAfter  *time.Time
	AcceptedBefore *time.Time
	Order          string
	Paged          bool
	Limit          *int
	Cursor         string
}

ListExecsRequest describes optional filters for ListExecs.

type ListExecsResult 

type ListExecsResult struct {
	Execs      []ExecView `json:"items"`
	NextCursor string     `json:"next_cursor"`
}

ListExecsResult describes the response returned by ListExecs.

type ListSnapsRequest 

type ListSnapsRequest struct {
	// Attached filters by whether a snap is currently attached to a box.
	Attached *bool
}

ListSnapsRequest describes optional filters for ListSnaps.

type MeView 

type MeView struct {
	UserID          string    `json:"user_id"`
	PrimaryEmail    string    `json:"primary_email"`
	DisplayName     string    `json:"display_name,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	IsSystemManager bool      `json:"is_system_manager"`
}

MeView describes one user account.

type MembershipRole 

type MembershipRole string

MembershipRole represents one organization membership role.

type MembershipView 

type MembershipView struct {
	OrgID        string         `json:"org_id"`
	UserID       string         `json:"user_id"`
	PrimaryEmail string         `json:"primary_email"`
	DisplayName  string         `json:"display_name,omitempty"`
	Role         MembershipRole `json:"role"`
	CreatedAt    time.Time      `json:"created_at"`
	UpdatedAt    time.Time      `json:"updated_at"`
	LastLoginAt  time.Time      `json:"last_login_at,omitempty"`
}

MembershipView describes one organization member.

type OpenFileOptions added in v0.5.0 

type OpenFileOptions struct {
	// Range is an optional HTTP byte range, for example "bytes=0-1023".
	// Single and multipart ranges supported by the gateway are accepted.
	Range string
}

OpenFileOptions controls one streamed file read.

type OrgHostsView 

type OrgHostsView struct {
	OrgID         string     `json:"org_id"`
	AssignedHosts int        `json:"assigned_hosts"`
	Hosts         []HostView `json:"hosts"`
}

OrgHostsView describes runtime host assignment for one organization.

type OrgKind 

type OrgKind string

OrgKind represents one organization kind. 

const (
	// OrgKindPersonal identifies one personal organization.
	OrgKindPersonal OrgKind = "personal"
	// OrgKindShared identifies one shared organization.
	OrgKindShared OrgKind = "shared"
)

Organization kinds returned by the control plane.

type OrgView 

type OrgView struct {
	OrgID               string                  `json:"org_id"`
	OrgCID              string                  `json:"org_cid"`
	DisplayName         string                  `json:"display_name"`
	Kind                OrgKind                 `json:"kind"`
	Role                MembershipRole          `json:"role"`
	CreatedBy           string                  `json:"created_by"`
	CreatedAt           time.Time               `json:"created_at"`
	CurrentSubscription CurrentSubscriptionView `json:"current_subscription"`
}

OrgView describes one organization visible to the caller.

type ProjectMembershipView 

type ProjectMembershipView struct {
	ProjectID    string      `json:"project_id"`
	UserID       string      `json:"user_id"`
	PrimaryEmail string      `json:"primary_email"`
	DisplayName  string      `json:"display_name,omitempty"`
	Role         ProjectRole `json:"role"`
	CreatedAt    time.Time   `json:"created_at"`
	UpdatedAt    time.Time   `json:"updated_at"`
}

ProjectMembershipView describes one project member.

type ProjectRole 

type ProjectRole string

ProjectRole represents one project membership role.

type ProjectSecretScope 

type ProjectSecretScope string

ProjectSecretScope represents where a secret is attached. 

const (
	// ProjectSecretScopeProject attaches one secret to project scope.
	ProjectSecretScopeProject ProjectSecretScope = "project"
	// ProjectSecretScopeBox attaches one secret to one box.
	ProjectSecretScopeBox ProjectSecretScope = "box"
)

Secret scopes accepted by project and box secret APIs.

type ProjectSecretView 

type ProjectSecretView struct {
	SecretID         string             `json:"secret_id"`
	OrgID            string             `json:"org_id"`
	ProjectID        string             `json:"project_id"`
	Scope            ProjectSecretScope `json:"scope"`
	BoxID            string             `json:"box_id,omitempty"`
	Name             string             `json:"name,omitempty"`
	Placeholder      string             `json:"placeholder"`
	AllowedHosts     []string           `json:"allowed_hosts"`
	InjectHeaderName string             `json:"inject_header_name"`
	CreatedBy        string             `json:"created_by"`
	UpdatedBy        string             `json:"updated_by"`
	CreatedAt        time.Time          `json:"created_at"`
	UpdatedAt        time.Time          `json:"updated_at"`
}

ProjectSecretView describes one secret attached to project or box scope.

type ProjectView 

type ProjectView struct {
	ProjectID   string      `json:"project_id"`
	OrgID       string      `json:"org_id"`
	ProjectCID  string      `json:"project_cid"`
	DisplayName string      `json:"display_name"`
	Description string      `json:"description,omitempty"`
	Role        ProjectRole `json:"role"`
	CreatedBy   string      `json:"created_by"`
	CreatedAt   time.Time   `json:"created_at"`
	UpdatedAt   time.Time   `json:"updated_at"`
}

ProjectView describes one project visible to the caller.

type PublishSharedSnapRequest 

type PublishSharedSnapRequest struct {
	// Name is the shared snap catalog name.
	Name string `json:"name"`
	// Description is optional catalog text for this publication.
	Description string `json:"description,omitempty"`
	// SourceSnapID identifies the project-local snap to publish.
	SourceSnapID string `json:"source_snap_id"`
}

PublishSharedSnapRequest publishes one snap into the shared snap catalog.

type PullBackgroundExecOutputRequest 

type PullBackgroundExecOutputRequest struct {
	// Cursor resumes from one previously returned cursor. Leave empty to read from the beginning once.
	Cursor string
	// Wait asks the service to short-poll before returning when the cursor is currently at the live tail.
	Wait time.Duration
}

PullBackgroundExecOutputRequest describes one pull-output request.

type ReadDirPage added in v0.5.0 

type ReadDirPage struct {
	Entries []FileEntry `json:"entries"`
	Cursor  string      `json:"cursor,omitempty"`
}

ReadDirPage is one name-ordered directory page.

type ReadDirRequest added in v0.5.0 

type ReadDirRequest struct {
	// Limit is the maximum number of entries. Zero uses the gateway default.
	Limit int
	// Cursor continues a previous page for the same directory and filesystem view.
	Cursor string
}

ReadDirRequest controls one bounded directory page.

type RuntimeRequestView 

type RuntimeRequestView struct {
	RuntimeRequestID string `json:"runtime_request_id"`
	State            string `json:"state"`
	SessionID        string `json:"session_id,omitempty"`
	HostID           string `json:"host_id,omitempty"`
}

RuntimeRequestView describes one asynchronous runtime request.

type SSHKeyView 

type SSHKeyView struct {
	SSHKeyID    string     `json:"ssh_key_id"`
	Label       string     `json:"label"`
	Fingerprint string     `json:"fingerprint"`
	CreatedAt   time.Time  `json:"created_at"`
	LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
}

SSHKeyView describes one SSH key on the caller's account.

type SharedSnapDetailView 

type SharedSnapDetailView struct {
	OrgID         string                  `json:"org_id"`
	Name          string                  `json:"name"`
	LatestVersion int                     `json:"latest_version"`
	Publisher     string                  `json:"publisher"`
	Versions      []SharedSnapVersionView `json:"versions"`
}

SharedSnapDetailView describes one shared snap and its version history.

type SharedSnapLineView 

type SharedSnapLineView struct {
	OrgID                    string    `json:"org_id"`
	Name                     string    `json:"name"`
	LatestVersion            int       `json:"latest_version"`
	Publisher                string    `json:"publisher"`
	PublishedBy              string    `json:"published_by"`
	PublishedAt              time.Time `json:"published_at"`
	Description              string    `json:"description,omitempty"`
	SourceProjectID          string    `json:"source_project_id"`
	SourceProjectCID         string    `json:"source_project_cid"`
	SourceProjectDisplayName string    `json:"source_project_display_name"`
}

SharedSnapLineView describes one shared snap in list results.

type SharedSnapVersionView 

type SharedSnapVersionView struct {
	OrgID                    string    `json:"org_id"`
	Name                     string    `json:"name"`
	Version                  int       `json:"version"`
	Description              string    `json:"description,omitempty"`
	PublishedBy              string    `json:"published_by"`
	PublishedAt              time.Time `json:"published_at"`
	SourceProjectID          string    `json:"source_project_id"`
	SourceProjectCID         string    `json:"source_project_cid"`
	SourceProjectDisplayName string    `json:"source_project_display_name"`
}

SharedSnapVersionView describes one published shared snap version.

type SnapOwnedStorage 

type SnapOwnedStorage struct {
	Bytes      uint64    `json:"bytes"`
	Objects    uint64    `json:"objects"`
	MeasuredAt time.Time `json:"measured_at"`
}

SnapOwnedStorage is the cached first-owner object storage attribution for one snap.

type SnapSize 

type SnapSize struct {
	UsedBytes  uint64    `json:"used_bytes"`
	UsedInodes uint64    `json:"used_inodes"`
	MeasuredAt time.Time `json:"measured_at"`
}

SnapSize is the cached filesystem usage measured for one snap.

type SnapState 

type SnapState string

SnapState represents the current snap state.

type SnapTreeAttachedBoxView 

type SnapTreeAttachedBoxView struct {
	BoxID        string   `json:"box_id"`
	DesiredShape string   `json:"desired_shape"`
	State        BoxState `json:"state"`
}

SnapTreeAttachedBoxView describes the box attached to one snap tree node.

type SnapTreeNodeView 

type SnapTreeNodeView struct {
	SnapID              string                   `json:"snap_id"`
	ParentSnapID        string                   `json:"parent_snap_id,omitempty"`
	Creator             string                   `json:"creator"`
	CreatorDisplayName  string                   `json:"creator_display_name,omitempty"`
	CreatorPrimaryEmail string                   `json:"creator_primary_email,omitempty"`
	CreatedAt           time.Time                `json:"created_at"`
	State               SnapState                `json:"state"`
	Reason              string                   `json:"reason,omitempty"`
	SourceImageRef      string                   `json:"source_image_ref,omitempty"`
	SourceImageDigest   string                   `json:"source_image_digest,omitempty"`
	SourceImagePlatform string                   `json:"source_image_platform,omitempty"`
	AttachedBox         *SnapTreeAttachedBoxView `json:"attached_box,omitempty"`
}

SnapTreeNodeView describes one node inside a snap ancestry tree.

type SnapTreeView 

type SnapTreeView struct {
	Supported  bool               `json:"supported"`
	RootSnapID string             `json:"root_snap_id,omitempty"`
	Nodes      []SnapTreeNodeView `json:"nodes,omitempty"`
}

SnapTreeView describes the ancestry tree returned for one snap.

type SnapView 

type SnapView struct {
	SnapID              string            `json:"snap_id"`
	OrgID               string            `json:"org_id"`
	ProjectID           string            `json:"project_id"`
	Creator             string            `json:"creator"`
	CreatedAt           time.Time         `json:"created_at"`
	LastUsedAt          time.Time         `json:"last_used_at"`
	State               SnapState         `json:"state"`
	InUseReason         string            `json:"inuse_reason,omitempty"`
	Reason              string            `json:"reason,omitempty"`
	ParentChain         []string          `json:"parent_chain,omitempty"`
	SourceImageRef      string            `json:"source_image_ref,omitempty"`
	SourceImageDigest   string            `json:"source_image_digest,omitempty"`
	SourceImagePlatform string            `json:"source_image_platform,omitempty"`
	Attached            bool              `json:"attached"`
	AttachedBoxID       string            `json:"attached_box_id,omitempty"`
	FileAccessURL       string            `json:"file_access_url,omitempty"`
	Size                *SnapSize         `json:"size,omitempty"`
	OwnedStorage        *SnapOwnedStorage `json:"owned_storage,omitempty"`
}

SnapView describes one snap. FileAccessURL reads a detached snap's immutable filesystem or the owning Box filesystem while the snap is attached.

type TTYSize 

type TTYSize struct {
	// Rows is the terminal height in character cells.
	Rows uint32 `json:"rows,omitempty"`
	// Cols is the terminal width in character cells.
	Cols uint32 `json:"cols,omitempty"`
}

TTYSize describes terminal size in rows and columns.

type UpdateBoxRequest 

type UpdateBoxRequest struct {
	// Description replaces the durable box description when non-nil.
	Description *string `json:"description,omitempty"`
	// Labels replaces the full durable label map when non-nil.
	Labels *map[string]string `json:"labels,omitempty"`
	// DesiredShape replaces the durable target shape when non-nil.
	DesiredShape *string `json:"desired_shape,omitempty"`
	// NetworkMode replaces the durable network mode when non-nil.
	NetworkMode *BoxNetworkMode `json:"network_mode,omitempty"`
}

UpdateBoxRequest updates mutable box fields.

type UpdateMeRequest 

type UpdateMeRequest struct {
	// DisplayName replaces the current account display name when non-nil.
	DisplayName *string `json:"display_name,omitempty"`
}

UpdateMeRequest updates caller profile fields.

type UpdateMembershipRequest 

type UpdateMembershipRequest struct {
	// Role is the desired organization role.
	Role MembershipRole `json:"role"`
}

UpdateMembershipRequest updates one organization membership.

type UpdateOrgRequest 

type UpdateOrgRequest struct {
	// DisplayName replaces the current organization display name when non-nil.
	DisplayName *string `json:"display_name,omitempty"`
	// OrgCID replaces the durable organization CID when non-nil.
	OrgCID *string `json:"org_cid,omitempty"`
}

UpdateOrgRequest updates mutable organization fields.

type UpdateProjectMembershipRequest 

type UpdateProjectMembershipRequest struct {
	// Role is the desired project role.
	Role ProjectRole `json:"role"`
}

UpdateProjectMembershipRequest updates one project membership.

type UpdateProjectRequest 

type UpdateProjectRequest struct {
	// DisplayName replaces the current project display name when non-nil.
	DisplayName *string `json:"display_name,omitempty"`
	// Description replaces the current project description when non-nil.
	Description *string `json:"description,omitempty"`
}

UpdateProjectRequest updates mutable project fields.

type UpdateProjectSecretRequest 

type UpdateProjectSecretRequest struct {
	// Name replaces the stored human-readable secret name when non-nil.
	Name *string `json:"name,omitempty"`
	// Value replaces the stored secret value when non-nil.
	Value *string `json:"value,omitempty"`
	// AllowedHosts replaces the full allowed-host set when non-nil.
	AllowedHosts *[]string `json:"allowed_hosts,omitempty"`
	// InjectHeaderName replaces the header selector when non-nil.
	InjectHeaderName *string `json:"inject_header_name,omitempty"`
}

UpdateProjectSecretRequest updates one existing project or box secret.

type WriteBackgroundExecStdinRequest 

type WriteBackgroundExecStdinRequest struct {
	// Data is the raw stdin chunk to send in this request.
	Data []byte
	// CloseStdin requests EOF immediately after Data is written.
	CloseStdin bool
}

WriteBackgroundExecStdinRequest describes one background exec stdin write.

Source Files

View all Source files

Directories

Path Synopsis
cmd
normalizeswagger command
internal
codegenpatch
Package codegenpatch provides external schema types injected into the generated swagger client to preserve PATCH request semantics.
 Package codegenpatch provides external schema types injected into the generated swagger client to preserve PATCH request semantics.
generated/client
generated/client/boxes
generated/client/execs
generated/client/org_access
generated/client/org_members
generated/client/projects
generated/client/shared_snaps
generated/client/snaps
generated/models

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.