Sprites

Sprites provides a direct interface for defining containers at runtime and securely running arbitrary code inside them.

This can be useful if, for example, you want to:

• Execute code generated by a language model
• Create isolated environments for running untrusted code
• Check out a git repository and run a command against it, like a test suite or linter
• Run containers with arbitrary dependencies and setup scripts

Each individual environment is called a Sprite and can be created using the CLI or SDKs:

CLI

# Create a sprite
sprite create my-sprite

# Execute commands
sprite exec python -c "print('hello')"

# Stream output from long-running commands
sprite exec "for i in {1..10}; do date +%T; sleep 0.5; done"

# Destroy when done
sprite destroy my-sprite

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 Timeouts

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

Sprites currently use a fixed resource configuration (8 vCPUs, 8192 MB RAM, 100 GB storage). These values are not configurable yet.

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()

Environments

Environment Variables

Set environment variables for command execution:

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

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 attachCmd = sprite.attachSession(sessionId);
attachCmd.stdout.pipe(process.stdout);

Go

// Create a detachable session
cmd := sprite.CreateDetachableSession("npm", "run", "dev")
cmd.Stdout = os.Stdout
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)
}

Referencing Sprites

By Name

If you have the name of a Sprite, you can get a handle to it:

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")

Related Documentation

Lifecycle and Persistence

Understand sprite states, hibernation, and automatic persistence

Networking and URLs

Access sprites via HTTP and configure network settings

Checkpoints

Save and restore sprite state with checkpoints

JavaScript SDK

Programmatic sprite management in JavaScript and TypeScript

Go SDK

Native Go client for the Sprites API

CLI Reference

Complete command-line interface documentation