Quickstart

This guide covers installation, your first Sprite, and everything you need to build with persistent execution environments.

Install the CLI

Install with our install script (macOS/Linux):

curl -fsSL https://sprites.dev/install.sh | sh

This auto-detects your platform, downloads the binary with checksum verification, and installs to ~/.local/bin.

For Windows or manual installation, see CLI Installation or download from GitHub Releases.

Verify installation:

sprite --help

Authenticate

Sprites uses your Fly.io account for authentication:

sprite org auth

This opens a browser window to authenticate with Fly.io.

If authentication fails, try running fly auth logout followed by fly auth login first, then retry sprite org auth.

Create Your First Sprite

sprite create my-first-sprite

This creates a new Sprite with default configuration, running and ready to accept commands.

Set it as your active Sprite to avoid adding -s my-first-sprite to every command:

sprite use my-first-sprite

Run Commands

Execute commands in your Sprite:

# Run a simple command
sprite exec echo "Hello, Sprites!"

# Run multiple commands
sprite exec "cd /tmp && ls -la"

# Open an interactive shell
sprite console

Explore the Environment

Sprites come pre-configured with common development tools:

# Check available runtimes
sprite exec "node --version && python3 --version && go version"

# Install packages
sprite exec "pip install requests"

# Clone a repository
sprite exec "git clone https://github.com/your/repo.git"

Persistence in Action

Your Sprite’s filesystem persists between commands:

# Create a file
sprite exec "echo 'Hello' > /home/sprite/greeting.txt"

# Later, it's still there
sprite exec "cat /home/sprite/greeting.txt"

View Your Sprite’s URL

Every Sprite has a unique HTTP URL:

sprite url

Manage Sprites

# List all sprites
sprite list

# Destroy when done
sprite destroy my-first-sprite

---

Using the SDKs

Beyond the CLI, you can create and manage Sprites programmatically:

JavaScript

import { SpritesClient } from '@fly/sprites';

const client = new SpritesClient(process.env.SPRITE_TOKEN);

const sprite = await client.createSprite('my-sprite');

// Execute a command
const result = await sprite.execFile('python', ['-c', "print('hello')"]);
console.log(result.stdout);

// Stream output from long-running commands
const cmd = sprite.spawn('bash', ['-c', 'for i in {1..10}; do date +%T; sleep 0.5; done']);
for await (const line of cmd.stdout) {
  process.stdout.write(line);
}

await sprite.delete();

Go

package main

import (
    "context"
    "fmt"
    "io"
    "os"

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

func main() {
    ctx := context.Background()
    client := sprites.New(os.Getenv("SPRITE_TOKEN"))

    sprite, _ := client.CreateSprite(ctx, "my-sprite", nil)
    defer client.DeleteSprite(ctx, "my-sprite")

    // Execute a command
    cmd := sprite.Command("python", "-c", "print('hello')")
    output, _ := cmd.Output()
    fmt.Println(string(output))

    // Stream output from long-running commands
    cmd = sprite.Command("bash", "-c", "for i in {1..10}; do date +%T; sleep 0.5; done")
    stdout, _ := cmd.StdoutPipe()
    cmd.Start()
    io.Copy(os.Stdout, stdout)
    cmd.Wait()
}

---

Lifecycle

Automatic Hibernation

Sprites automatically hibernate when inactive, with no compute charges while idle. When you execute a command or make a request to a Sprite’s URL, it automatically wakes up with all your data intact.

Timeouts

Sprites currently hibernate after 30 seconds of inactivity. This timeout is not configurable yet.

Idle Detection

A Sprite is considered active if any of the following are true:

1. It has an active command running (via exec)
2. Its stdin is being written to
3. It has an open TCP connection over its URL
4. A detachable session is running

---

Configuration

Resource Allocation

Sprites currently use a fixed resource configuration (8 vCPUs, 8192 MB RAM, 100 GB storage). These values are not configurable yet. (SDK config fields are accepted but ignored by the API.)

Working Directory

Set the working directory for command execution:

CLI

sprite exec -dir /home/sprite/project npm test

JavaScript

const result = await sprite.exec('npm test', {
  cwd: '/home/sprite/project',
});

Go

cmd := sprite.Command("npm", "test")
cmd.Dir = "/home/sprite/project"
output, err := cmd.Output()

Environment Variables

CLI

sprite exec -env MY_SECRET=hello bash -c 'echo $MY_SECRET'

JavaScript

const result = await sprite.execFile('bash', ['-lc', 'echo $MY_SECRET'], {
  env: { MY_SECRET: 'hello' },
});
console.log(result.stdout); // hello

Go

cmd := sprite.Command("bash", "-c", "echo $MY_SECRET")
cmd.Env = []string{"MY_SECRET=hello"}
output, _ := cmd.Output()
fmt.Println(string(output)) // hello

---

Environment

Pre-installed Tools

The default Sprite environment includes:

• Languages: Node.js, Python, Go, Ruby, Rust, Elixir/Erlang, Java, Bun, Deno
• AI Tools: Claude CLI, Gemini CLI, OpenAI Codex, Cursor
• Utilities: Git, curl, wget, vim, and common development tools

Custom Setup

Run setup commands after creating a Sprite:

JavaScript

const sprite = await client.createSprite('my-sprite');

// Install custom dependencies
await sprite.exec('pip install pandas numpy matplotlib');
await sprite.exec('npm install -g typescript');

// Clone a repository
await sprite.exec('git clone https://github.com/your/repo.git /home/sprite/project');

Go

sprite, _ := client.CreateSprite(ctx, "my-sprite", nil)

// Install custom dependencies
sprite.Command("pip", "install", "pandas", "numpy", "matplotlib").Run()
sprite.Command("npm", "install", "-g", "typescript").Run()

// Clone a repository
sprite.Command("git", "clone", "https://github.com/your/repo.git", "/home/sprite/project").Run()

---

Interactive Sessions

TTY Mode

For interactive applications, enable TTY mode:

CLI

# Open interactive shell (TTY enabled by default)
sprite console

# Or with exec
sprite exec -tty bash

JavaScript

const cmd = sprite.spawn('bash', [], {
  tty: true,
  rows: 24,
  cols: 80,
});

// Write to stdin
cmd.stdin.write('echo hello\n');

// Read from stdout
cmd.stdout.on('data', (data) => {
  process.stdout.write(data);
});

// Resize terminal
cmd.resize(30, 100);

Go

cmd := sprite.Command("bash")
cmd.SetTTY(true)
cmd.SetTTYSize(24, 80)

cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr

cmd.Start()

// Resize later
cmd.Resize(30, 100)

cmd.Wait()

Detachable Sessions

Create sessions that persist even after disconnecting:

CLI

# Create a detachable session
sprite exec -detachable "npm run dev"

# List active sessions
sprite exec

# Attach to a session
sprite exec -id <session-id>

JavaScript

// Create a detachable session
const sessionCmd = sprite.createSession('npm', ['run', 'dev']);
let sessionId;

sessionCmd.on('message', (msg) => {
  if (msg && msg.type === 'session_info') {
    sessionId = msg.session_id;
  }
});

// ... later, attach to it
const cmd = sprite.attachSession(sessionId);
cmd.stdout.pipe(process.stdout);

Go

// Create a detachable session
cmd := sprite.CreateDetachableSession("npm", "run", "dev")
cmd.Start()

// List sessions to get the session ID
sessions, _ := client.ListSessions(ctx, "my-sprite")
sessionID := sessions[0].ID

// ... later, attach to it
cmd = sprite.AttachSessionContext(ctx, sessionID)
cmd.Stdout = os.Stdout
cmd.Run()

Listing Sessions

CLI

sprite exec

JavaScript

const sessions = await sprite.listSessions();
for (const session of sessions) {
  console.log(`${session.id}: ${session.command}`);
}

Go

sessions, _ := client.ListSessions(ctx, "my-sprite")
for _, session := range sessions {
    fmt.Printf("%s: %s\n", session.ID, session.Command)
}

---

Managing Sprites

Referencing by Name

CLI

# Set active sprite for current directory
sprite use my-sprite

# Commands now use this sprite
sprite exec echo "hello"

JavaScript

// Get sprite by name (doesn't verify it exists)
const sprite = client.sprite('my-sprite');

// Get sprite and verify it exists
const sprite = await client.getSprite('my-sprite');

Go

// Get sprite by name (doesn't verify it exists)
sprite := client.Sprite("my-sprite")

// Get sprite and verify it exists
sprite, err := client.GetSprite(ctx, "my-sprite")

Listing Sprites

CLI

# List all sprites
sprite list

# List with prefix filter
sprite list --prefix "dev-"

JavaScript

// List all sprites
const sprites = await client.listAllSprites();

// List with prefix filter
const devSprites = await client.listAllSprites('dev-');

// Paginated listing
const page = await client.listSprites({ maxResults: 50 });
console.log(page.sprites);
if (page.hasMore) {
  const nextPage = await client.listSprites({
    continuationToken: page.nextContinuationToken,
  });
}

Go

// List all sprites
sprites, _ := client.ListAllSprites(ctx, "")

// List with prefix filter
devSprites, _ := client.ListAllSprites(ctx, "dev-")

// Paginated listing
page, _ := client.ListSprites(ctx, &sprites.ListOptions{MaxResults: 50})
fmt.Println(page.Sprites)
if page.HasMore {
    nextPage, _ := client.ListSprites(ctx, &sprites.ListOptions{
        ContinuationToken: page.NextContinuationToken,
    })
}

---

HTTP Access

Every Sprite has a unique URL for HTTP access:

CLI

# Get sprite URL
sprite url

# Make URL public (no auth required)
sprite url update --auth public

# Make URL require sprite auth (default)
sprite url update --auth default

JavaScript

// Get sprite info including URL
const info = await client.getSprite('my-sprite');
console.log(info.url);

Go

// Get sprite info including URL
info, _ := client.GetSprite(ctx, "my-sprite")
fmt.Println(info.URL)

Updating URL settings is available via the CLI, Go SDK, or REST API (the JS SDK does not expose a helper yet).

---

Port Forwarding

Forward local ports to your Sprite:

CLI

# Forward local port 3000 to sprite port 3000
sprite proxy 3000

# Forward multiple ports
sprite proxy 3000 8080 5432

Go

// Forward single port
session, _ := client.ProxyPort(ctx, "my-sprite", 3000, 3000)
defer session.Close()
// localhost:3000 now forwards to sprite:3000

// Forward multiple ports
sessions, _ := client.ProxyPorts(ctx, "my-sprite", []sprites.PortMapping{
    {LocalPort: 3000, RemotePort: 3000},
    {LocalPort: 8080, RemotePort: 80},
})

Port Notifications

Get notified when ports open in your Sprite:

JavaScript

const cmd = sprite.spawn('npm', ['run', 'dev']);

cmd.on('message', (msg) => {
  if (msg.type === 'port_opened') {
    console.log(`Port ${msg.port} opened on ${msg.address} by PID ${msg.pid}`);
    // Auto-forward or notify user
  }
});

Go

cmd := sprite.Command("npm", "run", "dev")
cmd.TextMessageHandler = func(data []byte) {
    var notification sprites.PortNotificationMessage
    json.Unmarshal(data, &notification)

    if notification.Type == "port_opened" {
        fmt.Printf("Port %d opened on %s by PID %d\n", notification.Port, notification.Address, notification.PID)
    }
}
cmd.Run()

---

Checkpoints

Save and restore Sprite state:

CLI

# Create a checkpoint
sprite checkpoint create

# List checkpoints
sprite checkpoint list

# Restore from checkpoint
sprite restore <checkpoint-id>

See Checkpoints and Restore for more details.

---

Error Handling

JavaScript

import { ExecError } from '@fly/sprites';

try {
  await sprite.execFile('bash', ['-lc', 'exit 1']);
} catch (error) {
  if (error instanceof ExecError) {
    console.log('Exit code:', error.exitCode);
    console.log('Stdout:', error.stdout);
    console.log('Stderr:', error.stderr);
  }
}

Go

cmd := sprite.Command("bash", "-lc", "exit 1")
err := cmd.Run()

if err != nil {
    if exitErr, ok := err.(*sprites.ExitError); ok {
        fmt.Printf("Exit code: %d\n", exitErr.ExitCode())
    }
}

---

Cleanup

Always clean up Sprites when you’re done:

CLI

sprite destroy my-sprite

JavaScript

await sprite.delete();
// or
await client.deleteSprite('my-sprite');

Go

err := client.DeleteSprite(ctx, "my-sprite")

---

Optional: Mount Sprite Filesystem Locally

Add this helper function to your .zshrc or .bashrc to mount your Sprite’s home directory locally:

# Add to ~/.zshrc
sc() {
  local sprite_name="${1:-$(sprite use)}"
  local mount_point="/tmp/sprite-${sprite_name}"
  mkdir -p "$mount_point"
  sshfs -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3 \
    "sprite@${sprite_name}.sprites.dev:" "$mount_point"
  cd "$mount_point"
}

Then use it with:

sc my-sprite  # Mounts and cd's to the sprite's filesystem

---

Next Steps

• CLI Reference - Full command documentation
• JavaScript SDK - Complete SDK reference
• Go SDK - Native Go integration
• Lifecycle & Persistence - Deep dive into how Sprites work
• Networking - URLs, ports, and connectivity