Sprite — Sprites Go SDK API reference

The Sprite type represents a single sprite instance. You obtain a *Sprite either by calling client.Sprite(name) for a lightweight handle to an existing sprite, or through CreateSprite, GetSprite, and the list methods which return sprites with fields populated from the API. Once you have a *Sprite you can run commands, manage services, checkpoint state, proxy ports, and more.

Fields

These fields are populated when a *Sprite is returned by GetSprite, ListAllSprites, or similar methods that fetch from the API.

string

Unique identifier assigned by the server.

OrganizationName

string

Name of the organization that owns this sprite.

Status

string

Current lifecycle status (e.g., "running", "warm", "cold", "created").

Config

*SpriteConfig

Resource configuration for the sprite.

Show SpriteConfig fields

RamMB

int

Memory allocation in megabytes.

CPUs

int

Number of CPU cores.

Region

string

Deployment region (e.g., "iad").

StorageGB

int

Storage allocation in gigabytes.

Environment

map[string]string

Environment variables set on the sprite.

CreatedAt

time.Time

When the sprite was created.

UpdatedAt

time.Time

When the sprite was last updated.

BucketName

string

Name of the storage bucket associated with this sprite.

PrimaryRegion

string

Primary deployment region.

URL

string

Public URL for the sprite, if configured.

URLSettings

*URLSettings

URL authentication settings.

Show URLSettings fields

Auth

string

Authentication mode for the public URL.

PrivateAccess

string

Private access configuration.

Labels

[]string

Labels attached to the sprite.

LastRunningAt

*time.Time

When the sprite was last running. Nil if never run.

LastWarmingAt

*time.Time

When the sprite last entered a warming state. Nil if never warmed.

Accessors

`Name`

func (s *Sprite) Name() string

Returns the sprite’s name.

returns

string

The sprite name.

`Client`

func (s *Sprite) Client() *Client

Returns the *Client associated with this sprite.

returns

*Client

The client that owns this sprite handle.

`Organization`

func (s *Sprite) Organization() *OrganizationInfo

Returns the organization information associated with this sprite, or nil if none was set.

returns

*OrganizationInfo

Organization context, or nil.

Lifecycle

`Destroy`

func (s *Sprite) Destroy() error

Deletes the sprite using context.Background(). Convenience wrapper around Delete.

error

Non-nil on failure.

`Delete`

func (s *Sprite) Delete(ctx context.Context) error

Deletes the sprite with context.

ctx

context.Context

required

Context for the HTTP request.

error

Non-nil on failure.

`Upgrade`

func (s *Sprite) Upgrade(ctx context.Context) error

Upgrades the sprite to the latest available version.

ctx

context.Context

required

Context for the HTTP request.

error

Non-nil on failure.

`UpdateURLSettings`

func (s *Sprite) UpdateURLSettings(ctx context.Context, settings *URLSettings) error

Updates the URL authentication settings for this sprite.

ctx

context.Context

required

Context for the HTTP request.

settings

*URLSettings

required

New URL settings to apply.

error

Non-nil on failure.

Commands

`Command`

func (s *Sprite) Command(name string, arg ...string) *Cmd

Returns a new *Cmd to execute the named program with the given arguments on the sprite. The returned Cmd is not started until Run, Start, or Output is called. Uses context.Background().

name

string

required

Path or name of the program to execute (e.g., "python", "/usr/bin/env").

arg

...string

Arguments to pass to the program.

returns

*Cmd

Command ready to be configured and started.

out, err := sprite.Command("python", "-c", "print(2+2)").Output()
fmt.Println(string(out)) // "4"

`CommandContext`

func (s *Sprite) CommandContext(ctx context.Context, name string, arg ...string) *Cmd

Like Command, but associates a context. If the context is cancelled before the command completes, the process is killed. Panics if ctx is nil.

ctx

context.Context

required

Context used to cancel or time out the command. Must not be nil.

name

string

required

Path or name of the program to execute.

arg

...string

Arguments to pass to the program.

returns

*Cmd

Command ready to be configured and started.

Filesystem

`Filesystem`

func (s *Sprite) Filesystem() FS

Returns an FS rooted at / that provides both read and write operations on the sprite’s filesystem.

returns

Filesystem interface implementing io/fs.FS, fs.StatFS, fs.ReadFileFS, fs.ReadDirFS, and write operations (WriteFile, Mkdir, MkdirAll, Remove, RemoveAll, Rename, Copy, Chmod).

`FilesystemAt`

func (s *Sprite) FilesystemAt(workingDir string) FS

Returns an FS rooted at the given directory.

workingDir

string

required

Absolute path to use as the working directory root.

returns

Filesystem interface scoped to the given directory.

Proxy

`ProxyPort`

func (s *Sprite) ProxyPort(ctx context.Context, localPort, remotePort int) (*ProxySession, error)

Creates a TCP proxy that forwards connections from localPort on localhost to remotePort on the sprite. Returns a *ProxySession that must be closed when no longer needed.

ctx

context.Context

required

Context for the proxy session lifecycle.

localPort

int

required

Port to listen on locally.

remotePort

int

required

Port to proxy to on the sprite.

session

*ProxySession

Active proxy session.

Show ProxySession fields

LocalPort

int

Local listening port.

RemotePort

int

Remote port on the sprite.

RemoteHost

string

Optional specific host to connect to. Defaults to "localhost" if empty.

error

Non-nil on failure.

session, err := sprite.ProxyPort(ctx, 8080, 3000)
if err != nil {
    log.Fatal(err)
}
defer session.Close()
// Traffic to localhost:8080 is now forwarded to the sprite's port 3000

`ProxyPorts`

func (s *Sprite) ProxyPorts(ctx context.Context, mappings []PortMapping) ([]*ProxySession, error)

Creates proxy sessions for multiple port mappings in a single call. If any mapping fails, all previously created sessions are closed before the error is returned.

ctx

context.Context

required

Context for the proxy sessions.

mappings

[]PortMapping

required

List of port mappings to proxy.

Show PortMapping fields

LocalPort

int

Local listening port.

RemotePort

int

Remote port on the sprite.

RemoteHost

string

Optional specific host. Defaults to "localhost" if empty.

sessions

[]*ProxySession

Active proxy sessions, one per mapping.

error

Non-nil on failure.

`ProxySocket`

func (s *Sprite) ProxySocket(ctx context.Context, network, addr string) (net.Conn, error)

Establishes a single proxied net.Conn to the given address on the sprite. Only "tcp" is supported for network.

ctx

context.Context

required

Context for the connection.

network

string

required

Network type. Only "tcp" is supported.

addr

string

required

Address in "host:port" format to connect to on the sprite.

conn

net.Conn

Connected network connection.

error

Non-nil on failure.

Sessions

`ListSessions`

func (s *Sprite) ListSessions(ctx context.Context) ([]*Session, error)

Lists active execution sessions on the sprite.

ctx

context.Context

required

Context for the HTTP request.

sessions

[]*Session

Active sessions.

Show Session fields

string

Session identifier.

Command

string

Command string for this session.

Workdir

string

Working directory of the session.

Created

time.Time

When the session was created.

BytesPerSecond

float64

Current I/O throughput.

IsActive

bool

Whether the session is currently active.

LastActivity

*time.Time

When the session last had activity.

TTY

bool

Whether the session is using a TTY.

error

Non-nil on failure.

`AttachSession`

func (s *Sprite) AttachSession(sessionID string) *Cmd

Returns a *Cmd that, when started, attaches to an existing session by ID. Uses context.Background().

sessionID

string

required

ID of the session to attach to.

returns

*Cmd

Command ready to attach to the session.

`AttachSessionContext`

func (s *Sprite) AttachSessionContext(ctx context.Context, sessionID string) *Cmd

Like AttachSession, but with a context.

ctx

context.Context

required

Context for the attach operation.

sessionID

string

required

ID of the session to attach to.

returns

*Cmd

Command ready to attach to the session.

Services

`ListServices`

func (s *Sprite) ListServices(ctx context.Context) ([]*ServiceWithState, error)

Retrieves all service definitions and their current runtime state.

ctx

context.Context

required

Context for the HTTP request.

services

[]*ServiceWithState

Services with their current state.

error

Non-nil on failure.

`GetService`

func (s *Sprite) GetService(ctx context.Context, serviceName string) (*ServiceWithState, error)

Retrieves a specific service and its runtime state.

ctx

context.Context

required

Context for the HTTP request.

serviceName

string

required

Name of the service to retrieve.

service

*ServiceWithState

Service definition and state.

Show ServiceWithState fields

Name

string

Service name.

Cmd

string

Command to run.

Args

[]string

Arguments for the command.

Needs

[]string

Services this service depends on.

HTTPPort

*int

HTTP port the service listens on, if applicable.

State

*ServiceState

Runtime state of the service.

error

Non-nil on failure.

`CreateService`

func (s *Sprite) CreateService(ctx context.Context, serviceName string, req *ServiceRequest) (*ServiceStream, error)

Creates or updates a service definition and returns a stream of log events from the startup process.

ctx

context.Context

required

Context for the HTTP request.

serviceName

string

required

Name to assign to the service.

req

*ServiceRequest

required

Service definition.

Show ServiceRequest fields

Cmd

string

Command to execute.

Args

[]string

Arguments for the command.

Needs

[]string

Names of services this service depends on.

HTTPPort

*int

HTTP port the service listens on.

stream

*ServiceStream

Streaming log events. Call Next() to read events, Close() when done.

error

Non-nil on failure.

stream, err := sprite.CreateService(ctx, "web", &sprites.ServiceRequest{
    Cmd:      "node",
    Args:     []string{"server.js"},
    HTTPPort: func() *int { p := 3000; return &p }(),
})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
stream.ProcessAll(func(event *sprites.ServiceLogEvent) error {
    fmt.Println(event.Type, event.Data)
    return nil
})

`StartService`

func (s *Sprite) StartService(ctx context.Context, serviceName string) (*ServiceStream, error)

Starts a service that is currently stopped and streams log events until it is running.

ctx

context.Context

required

Context for the HTTP request.

serviceName

string

required

Name of the service to start.

stream

*ServiceStream

Streaming log events.

error

Non-nil on failure.

`StopService`

func (s *Sprite) StopService(ctx context.Context, serviceName string) (*ServiceStream, error)

Stops a running service and streams log events until it has stopped.

ctx

context.Context

required

Context for the HTTP request.

serviceName

string

required

Name of the service to stop.

stream

*ServiceStream

Streaming log events.

error

Non-nil on failure.

`DeleteService`

func (s *Sprite) DeleteService(ctx context.Context, serviceName string) error

Deletes a service definition.

ctx

context.Context

required

Context for the HTTP request.

serviceName

string

required

Name of the service to delete.

error

Non-nil on failure.

`SignalService`

func (s *Sprite) SignalService(ctx context.Context, serviceName, signal string) error

Sends a signal to a running service.

ctx

context.Context

required

Context for the HTTP request.

serviceName

string

required

Name of the target service.

signal

string

required

Signal name (e.g., "HUP", "TERM", "KILL").

error

Non-nil on failure.

Checkpoints

`CreateCheckpoint`

func (s *Sprite) CreateCheckpoint(ctx context.Context) (*CheckpointStream, error)

Creates a checkpoint of the sprite’s current state and returns a stream of progress messages.

ctx

context.Context

required

Context for the HTTP request.

stream

*CheckpointStream

Streaming progress messages. Call Next() to read *StreamMessage values, Close() when done.

error

Non-nil on failure.

`CreateCheckpointWithComment`

func (s *Sprite) CreateCheckpointWithComment(ctx context.Context, comment string) (*CheckpointStream, error)

Creates a checkpoint with an optional descriptive comment.

ctx

context.Context

required

Context for the HTTP request.

comment

string

required

Human-readable comment for the checkpoint. Pass an empty string for no comment.

stream

*CheckpointStream

Streaming progress messages.

error

Non-nil on failure.

`ListCheckpoints`

func (s *Sprite) ListCheckpoints(ctx context.Context, historyFilter string) ([]*Checkpoint, error)

Lists checkpoints for this sprite, excluding auto-checkpoints. Pass an empty string for historyFilter to return all manual checkpoints.

ctx

context.Context

required

Context for the HTTP request.

historyFilter

string

required

Optional history filter expression. Pass "" for no filter.

checkpoints

[]*Checkpoint

List of checkpoints.

Show Checkpoint fields

string

Checkpoint identifier.

CreateTime

time.Time

When the checkpoint was created.

History

[]string

Checkpoint history entries.

Comment

string

Optional comment set at creation time.

IsAuto

bool

Whether this is an automatically created checkpoint.

error

Non-nil on failure.

`GetCheckpoint`

func (s *Sprite) GetCheckpoint(ctx context.Context, checkpointID string) (*Checkpoint, error)

Retrieves information about a specific checkpoint.

ctx

context.Context

required

Context for the HTTP request.

checkpointID

string

required

ID of the checkpoint to retrieve.

checkpoint

*Checkpoint

Checkpoint details.

error

Non-nil on failure.

`RestoreCheckpoint`

func (s *Sprite) RestoreCheckpoint(ctx context.Context, checkpointID string) (*RestoreStream, error)

Restores the sprite from the specified checkpoint and streams progress messages.

ctx

context.Context

required

Context for the HTTP request.

checkpointID

string

required

ID of the checkpoint to restore from.

stream

*RestoreStream

Streaming progress messages. Call Next() to read *StreamMessage values, Close() when done.

error

Non-nil on failure.

Network policy

`GetNetworkPolicy`

func (s *Sprite) GetNetworkPolicy(ctx context.Context) (*NetworkPolicy, error)

Retrieves the current network policy for this sprite.

ctx

context.Context

required

Context for the HTTP request.

policy

*NetworkPolicy

Current network policy.

Show NetworkPolicy fields

Rules

[]NetworkPolicyRule

List of network policy rules.

Show NetworkPolicyRule fields

Domain

string

Domain or CIDR this rule applies to.

Action

string

Action: "allow" or "deny".

Include

string

Named rule set to include.

error

Non-nil on failure.

`UpdateNetworkPolicy`

func (s *Sprite) UpdateNetworkPolicy(ctx context.Context, policy *NetworkPolicy) error

Replaces the network policy for this sprite with the provided policy.

ctx

context.Context

required

Context for the HTTP request.

policy

*NetworkPolicy

required

The new network policy to apply.

error

Non-nil on failure, including for invalid policy configurations.

err := sprite.UpdateNetworkPolicy(ctx, &sprites.NetworkPolicy{
    Rules: []sprites.NetworkPolicyRule{
        {Domain: "api.example.com", Action: "allow"},
        {Action: "deny"},
    },
})

Get Started

Guides

API Reference

Documentation Index

​Fields

​Accessors

​Name

​Client

​Organization

​Lifecycle

​Destroy

​Delete

​Upgrade

​UpdateURLSettings

​Commands

​Command

​CommandContext

​Filesystem

​Filesystem

​FilesystemAt

​Proxy

​ProxyPort

​ProxyPorts

​ProxySocket

​Sessions

​ListSessions

​AttachSession

​AttachSessionContext

​Services

​ListServices

​GetService

​CreateService

​StartService

​StopService

​DeleteService

​SignalService

​Checkpoints

​CreateCheckpoint

​CreateCheckpointWithComment

​ListCheckpoints

​GetCheckpoint

​RestoreCheckpoint

​Network policy

​GetNetworkPolicy

​UpdateNetworkPolicy

Build docs developers (and LLMs) love

Fields

Accessors

`Name`

`Client`

`Organization`

Lifecycle

`Destroy`

`Delete`

`Upgrade`

`UpdateURLSettings`

Commands

`Command`

`CommandContext`

Filesystem

`Filesystem`

`FilesystemAt`

Proxy

`ProxyPort`

`ProxyPorts`

`ProxySocket`

Sessions

`ListSessions`

`AttachSession`

`AttachSessionContext`

Services

`ListServices`

`GetService`

`CreateService`

`StartService`

`StopService`

`DeleteService`

`SignalService`

Checkpoints

`CreateCheckpoint`

`CreateCheckpointWithComment`

`ListCheckpoints`

`GetCheckpoint`

`RestoreCheckpoint`

Network policy

`GetNetworkPolicy`

`UpdateNetworkPolicy`