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
• Networking and URLs
• Checkpoints
• JavaScript SDK Reference
• Go SDK Reference
• CLI Reference