Types — Sprites Go SDK type reference

This page documents every exported type in the Sprites Go SDK. Types are grouped by concern. For method signatures that use these types, see the relevant API reference pages for proxy, filesystem, services, and checkpoints.

Sprite types

SpriteConfig

Hardware and region configuration applied when creating a sprite.

type SpriteConfig struct {
    RamMB     int    `json:"ram_mb,omitempty"`
    CPUs      int    `json:"cpus,omitempty"`
    Region    string `json:"region,omitempty"`
    StorageGB int    `json:"storage_gb,omitempty"`
}

RamMB

int

Memory allocation in megabytes. 0 uses the platform default.

CPUs

int

Number of virtual CPUs. 0 uses the platform default.

Region

string

Target region (e.g., "iad", "lhr"). Empty string uses the nearest region.

StorageGB

int

Persistent storage size in gigabytes. 0 uses the platform default.

URLSettings

Authentication and access control settings for the sprite’s HTTP URL.

type URLSettings struct {
    Auth          string `json:"auth,omitempty"`
    PrivateAccess string `json:"private_access,omitempty"`
}

Auth

string

Authentication method for the sprite’s public URL (e.g., "token").

PrivateAccess

string

Controls whether the sprite’s URL is accessible only from within the organization’s network.

SpriteInfo

Full sprite metadata as returned by list and get operations.

type SpriteInfo struct {
    ID            string            `json:"id"`
    Name          string            `json:"name"`
    Organization  string            `json:"organization"`
    Status        string            `json:"status"`
    Config        *SpriteConfig     `json:"config,omitempty"`
    Environment   map[string]string `json:"environment,omitempty"`
    CreatedAt     time.Time         `json:"created_at"`
    UpdatedAt     time.Time         `json:"updated_at"`
    BucketName    string            `json:"bucket_name,omitempty"`
    PrimaryRegion string            `json:"primary_region,omitempty"`
    URL           string            `json:"url,omitempty"`
    URLSettings   *URLSettings      `json:"url_settings,omitempty"`
    Labels        []string          `json:"labels,omitempty"`
    LastRunningAt *time.Time        `json:"last_running_at,omitempty"`
    LastWarmingAt *time.Time        `json:"last_warming_at,omitempty"`
}

string

Unique platform-assigned identifier.

Name

string

Human-readable name used in API calls.

Organization

string

Organization slug that owns the sprite.

Status

string

Current status: "running", "warm", "cold", or "stopped".

Config

*SpriteConfig

Hardware configuration.

Environment

map[string]string

Environment variables set on the sprite.

CreatedAt

time.Time

Creation timestamp.

UpdatedAt

time.Time

Last update timestamp.

BucketName

string

Object storage bucket associated with the sprite.

PrimaryRegion

string

Region where the sprite’s primary instance runs.

URL

string

Public HTTPS URL of the sprite, if exposed.

URLSettings

*URLSettings

Access control settings for the public URL.

Labels

[]string

User-defined labels for filtering and grouping.

LastRunningAt

*time.Time

When the sprite last entered the running state.

LastWarmingAt

*time.Time

When the sprite last entered the warm state.

CreateSpriteRequest

Request body for creating a new sprite.

type CreateSpriteRequest struct {
    Name        string            `json:"name"`
    Config      *SpriteConfig     `json:"config,omitempty"`
    Environment map[string]string `json:"environment,omitempty"`
    Labels      []string          `json:"labels,omitempty"`
}

Name

string

Desired sprite name. Must be unique within the organization.

Config

*SpriteConfig

Optional hardware configuration. Platform defaults are used when nil.

Environment

map[string]string

Environment variables to set on the sprite at creation.

Labels

[]string

Labels to attach to the sprite.

UpdateSpriteRequest

Request body for updating a sprite’s settings.

type UpdateSpriteRequest struct {
    URLSettings *URLSettings `json:"url_settings,omitempty"`
    Labels      []string     `json:"labels,omitempty"`
    ClearLabels bool         `json:"clear_labels,omitempty"`
}

URLSettings

*URLSettings

New URL access settings. nil leaves the current settings unchanged.

Labels

[]string

Labels to set or append.

ClearLabels

bool

When true, removes all existing labels before applying Labels.

CreateSpriteResponse

Response from a successful sprite creation request.

type CreateSpriteResponse struct {
    Name string `json:"name"`
}

Name

string

The name of the created sprite.

OrgInfo

Aggregate statistics for all sprites in an organization, included in list responses.

type OrgInfo struct {
    Name         string `json:"name"`
    Running      int    `json:"running"`
    Warm         int    `json:"warm"`
    Cold         int    `json:"cold"`
    RunningLimit int    `json:"running_limit"`
    WarmLimit    int    `json:"warm_limit"`
}

Name

string

Organization slug.

Running

int

Number of sprites currently in the running state.

Warm

int

Number of sprites in the warm (suspended but fast-resumable) state.

Cold

int

Number of sprites in the cold state.

RunningLimit

int

Maximum number of simultaneously running sprites allowed.

WarmLimit

int

Maximum number of simultaneously warm sprites allowed.

ListOptions

Pagination and filtering options for sprite list operations.

type ListOptions struct {
    Prefix            string
    MaxResults        int
    ContinuationToken string
}

Prefix

string

Return only sprites whose names start with this prefix.

MaxResults

int

Maximum number of sprites to return per page. 0 uses the server default.

ContinuationToken

string

Token from a previous SpriteList.NextContinuationToken for paginating results.

SpriteList

Paginated list of sprites returned by list operations.

type SpriteList struct {
    Sprites               []SpriteInfo `json:"sprites"`
    Org                   *OrgInfo     `json:"org,omitempty"`
    HasMore               bool         `json:"has_more"`
    NextContinuationToken string       `json:"next_continuation_token,omitempty"`
}

Sprites

[]SpriteInfo

Sprites on this page.

Org

*OrgInfo

Aggregate organization statistics. May be nil.

HasMore

bool

true when additional pages are available.

NextContinuationToken

string

Pass this value as ListOptions.ContinuationToken to fetch the next page.

OrganizationInfo

Organization context attached to a Sprite instance at construction time.

type OrganizationInfo struct {
    Name string
    URL  string
}

Name

string

Organization slug.

URL

string

Base URL for the organization’s API endpoint.

ListResult

Result of a full sprite listing, including the aggregate organization stats.

type ListResult struct {
    Sprites []*Sprite
    Org     *OrgInfo
}

Sprites

[]*Sprite

All sprites matching the query.

Org

*OrgInfo

Organization-level aggregate statistics.

Session types

Session

Represents an active or historical execution session on a sprite.

type Session struct {
    ID             string     `json:"id"`
    Command        string     `json:"command"`
    Workdir        string     `json:"workdir"`
    Created        time.Time  `json:"created"`
    BytesPerSecond float64    `json:"bytes_per_second"`
    IsActive       bool       `json:"is_active"`
    LastActivity   *time.Time `json:"last_activity,omitempty"`
    TTY            bool       `json:"tty"`
}

string

Unique session identifier.

Command

string

Command that was executed to create this session.

Workdir

string

Working directory the command ran in.

Created

time.Time

When the session was created.

BytesPerSecond

float64

Current throughput for the session’s I/O stream.

IsActive

bool

true if the session is still running.

LastActivity

*time.Time

Timestamp of the last I/O activity. nil if no activity has occurred.

TTY

bool

true if the session was started with a pseudo-TTY.

ExecOptions

Options passed to command execution methods.

type ExecOptions struct {
    WorkingDir  string
    Environment []string
    TTY         bool
    SessionID   string
    ControlMode bool
    InitialCols int
    InitialRows int
}

WorkingDir

string

Working directory for the command. Defaults to the sprite’s home directory.

Environment

[]string

Additional environment variables in KEY=VALUE format.

TTY

bool

Allocate a pseudo-TTY for the process.

SessionID

string

Attach to an existing session by ID instead of creating a new one.

ControlMode

bool

Use the control channel for multiplexed execution.

InitialCols

int

Initial terminal width in columns when TTY is true.

InitialRows

int

Initial terminal height in rows when TTY is true.

Checkpoint types

Checkpoint

Metadata for a single sprite checkpoint.

type Checkpoint struct {
    ID         string    `json:"id"`
    CreateTime time.Time `json:"create_time"`
    History    []string  `json:"history,omitempty"`
    Comment    string    `json:"comment,omitempty"`
    IsAuto     bool      `json:"is_auto,omitempty"`
}

string

Unique checkpoint identifier used in restore and get calls.

CreateTime

time.Time

When the checkpoint was created.

History

[]string

History branch identifiers associated with this checkpoint.

Comment

string

Optional human-readable label.

IsAuto

bool

true for platform-managed automatic checkpoints.

StreamMessage

Progress message emitted by CheckpointStream and RestoreStream.

type StreamMessage struct {
    Type  string `json:"type"`
    Data  string `json:"data,omitempty"`
    Error string `json:"error,omitempty"`
}

Type

string

Event type: "info", "stdout", "stderr", or "error".

Data

string

Progress message or output data.

Error

string

Error detail when Type is "error".

Proxy types

ProxyInitMessage

Initial handshake message sent over the WebSocket when establishing a proxy connection.

type ProxyInitMessage struct {
    Host string `json:"host"`
    Port int    `json:"port"`
}

Host

string

Target hostname inside the sprite (e.g., "localhost", "10.0.0.1").

Port

int

Target port number (1–65535).

ProxyResponseMessage

Server response to a ProxyInitMessage confirming the connection target.

type ProxyResponseMessage struct {
    Status string `json:"status"`
    Target string `json:"target"`
}

Status

string

"connected" on success; any other value indicates failure.

Target

string

Resolved host:port that the proxy is forwarding to.

PortNotificationMessage

Event emitted when a port is opened or closed inside a sprite.

type PortNotificationMessage struct {
    Type    string `json:"type"`
    Port    int    `json:"port"`
    Address string `json:"address"`
    PID     int    `json:"pid"`
}

Type

string

"port_opened" or "port_closed".

Port

int

Port number.

Address

string

Address the port is bound to, e.g., "127.0.0.1" or "0.0.0.0".

PID

int

Process ID that opened or closed the port.

Service types

Service

Definition of a managed service.

type Service struct {
    Name     string   `json:"name"`
    Cmd      string   `json:"cmd"`
    Args     []string `json:"args"`
    Needs    []string `json:"needs"`
    HTTPPort *int     `json:"http_port,omitempty"`
}

Name

string

Service identifier.

Cmd

string

Executable to run.

Args

[]string

Command arguments.

Needs

[]string

Services that must be running before this one starts.

HTTPPort

*int

Port the service’s HTTP interface listens on. Used for health checking.

ServiceState

Runtime state of a service.

type ServiceState struct {
    Name          string    `json:"name"`
    Status        string    `json:"status"`
    PID           int       `json:"pid,omitempty"`
    StartedAt     time.Time `json:"started_at,omitempty"`
    Error         string    `json:"error,omitempty"`
    RestartCount  int       `json:"restart_count,omitempty"`
    NextRestartAt time.Time `json:"next_restart_at,omitempty"`
}

Name

string

Service name.

Status

string

One of "stopped", "starting", "running", "stopping", or "failed".

PID

int

Process ID when the service is running; 0 otherwise.

StartedAt

time.Time

Timestamp of the most recent start.

Error

string

Error detail when Status is "failed".

RestartCount

int

Number of automatic restarts since the service was created.

NextRestartAt

time.Time

Scheduled time for the next automatic restart attempt.

ServiceWithState

Combined service definition and runtime state, as returned by ListServices and GetService.

type ServiceWithState struct {
    Service
    State *ServiceState `json:"state,omitempty"`
}

Service

Embedded service definition (see Service).

State

*ServiceState

Current runtime state. nil if the service has never been started.

ServiceRequest

Request body used with CreateService and CreateServiceWithDuration.

type ServiceRequest struct {
    Cmd      string   `json:"cmd"`
    Args     []string `json:"args,omitempty"`
    Needs    []string `json:"needs,omitempty"`
    HTTPPort *int     `json:"http_port,omitempty"`
}

Cmd

string

Executable to run (e.g., "node", "/usr/bin/python3").

Args

[]string

Arguments passed to the executable.

Needs

[]string

Names of services that must be running before this service starts.

HTTPPort

*int

Optional HTTP port for health checking.

ServiceLogEvent

A single event from a ServiceStream.

type ServiceLogEvent struct {
    Type      string            `json:"type"`
    Data      string            `json:"data,omitempty"`
    ExitCode  *int              `json:"exit_code,omitempty"`
    Timestamp int64             `json:"timestamp"`
    LogFiles  map[string]string `json:"log_files,omitempty"`
}

Type

string

Event type: "stdout", "stderr", "exit", "error", "complete", "started", "stopping", or "stopped".

Data

string

Log line or status message.

ExitCode

*int

Exit code, present on "exit" events.

Timestamp

int64

Unix timestamp in milliseconds.

LogFiles

map[string]string

Map of log file names to their paths on the sprite. Present on "complete" events.

Network policy types

NetworkPolicyRule

A single rule in a network egress policy.

type NetworkPolicyRule struct {
    Domain  string `json:"domain,omitempty"`
    Action  string `json:"action,omitempty"`
    Include string `json:"include,omitempty"`
}

Domain

string

Hostname or domain pattern to match. Omit for a catch-all rule.

Action

string

"allow" to permit traffic or "deny" to block it.

Include

string

Optional name of a named policy to inline at this rule’s position.

NetworkPolicy

Complete egress policy for a sprite.

type NetworkPolicy struct {
    Rules []NetworkPolicyRule `json:"rules"`
}

Rules

[]NetworkPolicyRule

Ordered list of rules evaluated top to bottom. The first matching rule wins.

Get Started

Guides

API Reference

Types — Sprites Go SDK type reference

Sprite types

SpriteConfig

URLSettings

SpriteInfo

CreateSpriteRequest

UpdateSpriteRequest

CreateSpriteResponse

OrgInfo

ListOptions

SpriteList

OrganizationInfo

ListResult

Session types

Session

ExecOptions

Checkpoint types

Checkpoint

StreamMessage

Proxy types

ProxyInitMessage

ProxyResponseMessage

PortNotificationMessage

Service types

Service

ServiceState

ServiceWithState

ServiceRequest

ServiceLogEvent

Network policy types

NetworkPolicyRule

NetworkPolicy

Build docs developers (and LLMs) love

Get Started

Guides

API Reference

Documentation Index

​Sprite types

​SpriteConfig

​URLSettings

​SpriteInfo

​CreateSpriteRequest

​UpdateSpriteRequest

​CreateSpriteResponse

​OrgInfo

​ListOptions

​SpriteList

​OrganizationInfo

​ListResult

​Session types

​Session

​ExecOptions

​Checkpoint types

​Checkpoint

​StreamMessage

​Proxy types

​ProxyInitMessage

​ProxyResponseMessage

​PortNotificationMessage

​Service types

​Service

​ServiceState

​ServiceWithState

​ServiceRequest

​ServiceLogEvent

​Network policy types

​NetworkPolicyRule

​NetworkPolicy

Build docs developers (and LLMs) love

Sprite types

SpriteConfig

URLSettings

SpriteInfo

CreateSpriteRequest

UpdateSpriteRequest

CreateSpriteResponse

OrgInfo

ListOptions

SpriteList

OrganizationInfo

ListResult

Session types

Session

ExecOptions

Checkpoint types

Checkpoint

StreamMessage

Proxy types

ProxyInitMessage

ProxyResponseMessage

PortNotificationMessage

Service types

Service

ServiceState

ServiceWithState

ServiceRequest

ServiceLogEvent

Network policy types

NetworkPolicyRule

NetworkPolicy