Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superfly/sprites-go/llms.txt

Use this file to discover all available pages before exploring further.

The Sprites Go SDK provides a Go-native way to execute commands on remote sprites. Its central design principle is compatibility with the standard library’s exec.Cmd type — the same fields (Path, Args, Env, Dir, Stdin, Stdout, Stderr) and the same methods (Run, Start, Wait, Output, CombinedOutput, StdinPipe, StdoutPipe, StderrPipe) work identically, but the process runs remotely on a sprite rather than on the local machine.

​
What the SDK does

You create a Client, get a Sprite handle by name, and call sprite.Command(...) to build a Cmd. From there the workflow is identical to running a local subprocess. The SDK handles authentication, WebSocket multiplexing, streaming I/O, exit codes, and error propagation so your code stays focused on business logic rather than transport details. 
package main

import (
    "fmt"
    "log"

    sprites "github.com/superfly/sprites-go"
)

func main() {
    client := sprites.New("your-auth-token")
    sprite := client.Sprite("my-sprite")

    output, err := sprite.Command("echo", "hello", "world").Output()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Output: %s", output)
}

​
Key capabilities

exec.Cmd-compatible API

sprite.Cmd mirrors exec.Cmd field-for-field and method-for-method. Existing Go subprocess code requires minimal changes to run remotely.

Streaming I/O

Attach io.Reader/io.Writer to Stdin, Stdout, and Stderr, or use StdinPipe, StdoutPipe, and StderrPipe for concurrent streaming over WebSocket.

TTY support

Call cmd.SetTTY(true) to run interactive commands with a pseudo-terminal. Resize the terminal at any time with cmd.SetTTYSize(rows, cols).

Context and cancellation

sprite.CommandContext(ctx, ...) ties command lifetime to a context.Context. The remote process is killed when the context is cancelled or times out.

Port forwarding

Forward local ports to services inside the sprite with sprite.ProxyPort or sprite.ProxyPorts. Receive real-time port-open/close notifications via cmd.TextMessageHandler.

Filesystem access

Read and write files inside a sprite’s filesystem directly from your Go code without running a subprocess.

Services

Create, start, stop, and signal long-running services inside a sprite. All service operations return streaming log events.

Checkpoints

Snapshot sprite state with sprite.CreateCheckpoint and restore it later with sprite.RestoreCheckpoint, both as streaming operations.

Network policy

Read and update the network policy for a sprite with sprite.GetNetworkPolicy and sprite.UpdateNetworkPolicy.

Signal forwarding

Send POSIX signals (INT, TERM, HUP, KILL, etc.) to a running remote process with cmd.Signal(signal).

​
Next steps

Quickstart

Install the SDK and run your first remote command in minutes.

Authentication

Learn how to create a client and exchange Fly.io credentials for a sprite token.

Build docs developers (and LLMs) love

Get started for freeTalk to us