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.

Every API call the Sprites Go SDK makes includes an Authorization: Bearer <token> header. You supply the token when you create the client and the SDK handles all credential propagation from there. This page covers how to obtain a token, the two client constructors available, and all functional options for tuning client behavior.

​
Obtaining a token

​
Using an existing token

If you already have a sprite access token, pass it directly to sprites.New: 
client := sprites.New("your-sprite-token")

​
Exchanging a Fly.io macaroon

sprites.CreateToken is a package-level function (no client required) that exchanges a Fly.io authentication token for a sprite access token. Use this during initial setup or in tooling that bootstraps credentials: 
import (
    "context"
    "fmt"
    "log"

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

func main() {
    ctx := context.Background()

    // flyMacaroon starts with "FlyV1"
    // orgSlug is "personal" or your organization name
    // inviteCode is optional — pass "" if not required
    token, err := sprites.CreateToken(ctx, flyMacaroon, "personal", "")
    if err != nil {
        log.Fatal(err)
    }

    client := sprites.New(token)
    fmt.Println("Client ready:", client)
}
The function POSTs to https://api.sprites.dev/v1/organizations/<orgSlug>/tokens. It uses HTTP/1.1 to avoid HTTP/2 header-size limits on the Fly.io edge proxy, so the call succeeds even when the Fly.io macaroon is large.
The flyMacaroon argument must be a valid Fly.io authentication token (starts with FlyV1). The returned token is a shorter sprite-specific credential that you store and reuse.

​
Creating a client

​
sprites.New

The primary constructor. Accepts a token and zero or more functional options: 
client := sprites.New(token string, opts ...Option) *Client

// Minimal — defaults to https://api.sprites.dev, 30-second HTTP timeout
client := sprites.New("your-token")

// With a custom base URL
client := sprites.New("your-token",
    sprites.WithBaseURL("http://localhost:8080"))

​
sprites.NewClient

An alternative constructor that takes the base URL and token as positional arguments. Useful when you prefer explicit parameters over functional options: 
client := sprites.NewClient(baseURL, token string) *Client

client := sprites.NewClient("https://api.sprites.dev", "your-token")
NewClient is equivalent to sprites.New(token, sprites.WithBaseURL(baseURL)).

​
Client options

Pass any number of options as the trailing arguments to sprites.New.

​
WithBaseURL

Override the default API endpoint. Useful for self-hosted deployments or local development: 
sprites.WithBaseURL(url string) Option

client := sprites.New("your-token",
    sprites.WithBaseURL("http://localhost:8080"))
Trailing slashes are stripped automatically.

​
WithHTTPClient

Provide a pre-configured *http.Client. Use this to set custom timeouts, add middleware, configure proxies, or attach transport-level TLS settings: 
sprites.WithHTTPClient(client *http.Client) Option

import "net/http"

httpClient := &http.Client{
    Timeout: 60 * time.Second,
}

client := sprites.New("your-token",
    sprites.WithHTTPClient(httpClient))
The SDK wraps the transport you provide to capture the Sprite-Version response header for internal feature negotiation. Replacing the transport after calling sprites.New will break version detection.

​
WithControlInitTimeout

Sets how long client.Sprite(name) waits when attempting to establish a multiplexed control connection before falling back to per-request direct WebSocket connections. The default is 2 seconds: 
sprites.WithControlInitTimeout(d time.Duration) Option

import "time"

client := sprites.New("your-token",
    sprites.WithControlInitTimeout(5*time.Second))
Control connections multiplex multiple exec sessions over a single WebSocket, which reduces latency and connection overhead for workloads that issue many short commands. If your sprite is slow to wake, increase this timeout so the SDK has time to establish the connection before the first command runs.

​
WithDisableControl

Disables control connections entirely. Every command opens its own direct WebSocket connection, which is the legacy behavior: 
sprites.WithDisableControl() Option

client := sprites.New("your-token",
    sprites.WithDisableControl())
Use this option for debugging, when you need deterministic per-request connections, or when connecting to a sprite server that does not support the control protocol.

​
Closing the client

When you are done, call client.Close() to release all pooled control connections: 
defer client.Close()

​
Configuration summary

client := sprites.New("your-sprite-token")

Build docs developers (and LLMs) love

Get started for freeTalk to us