Working with Sprites

After you’ve made it through the Quickstart, you’ve got a working Sprite and a sense of how to use it. This page covers what comes next: how Sprites behave over time, how to run persistent processes, how networking works, and how to shape the environment to fit your stack. Use it as a reference as you start building more with Sprites.

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 run on machines with a fixed resource cap: 8 vCPUs, 8192 MB RAM, and 100 GB storage. These limits are not configurable yet. The SDK accepts config fields, but the API ignores them.

Keep in mind, Sprites are not billed based on those limits. You are only charged for the resources your Sprite actually uses. The fixed config defines the current maximum resources each Sprite can consume, not a flat rate.

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

Elixir

{output, 0} = Sprites.cmd(sprite, "npm", ["test"],
  dir: "/home/sprite/project"
)

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

Elixir

{output, 0} = Sprites.cmd(sprite, "bash", ["-c", "echo $MY_SECRET"],
  env: [{"MY_SECRET", "hello"}]
)
IO.puts(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()

Elixir

{:ok, sprite} = Sprites.create(client, "my-sprite")

# Install custom dependencies
Sprites.cmd(sprite, "pip", ["install", "pandas", "numpy", "matplotlib"])
Sprites.cmd(sprite, "npm", ["install", "-g", "typescript"])

# Clone a repository
Sprites.cmd(sprite, "git", ["clone", "https://github.com/your/repo.git", "/home/sprite/project"])

---

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

Elixir

{:ok, cmd} = Sprites.spawn(sprite, "bash", [],
  tty: true,
  tty_rows: 24,
  tty_cols: 80
)

# Write to stdin
Sprites.write(cmd, "echo hello\n")

# Receive output
receive do
  {:stdout, ^cmd, data} -> IO.write(data)
end

# Resize terminal
Sprites.resize(cmd, 30, 100)

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

Elixir

# Create a detachable session
{:ok, cmd} = Sprites.spawn(sprite, "npm", ["run", "dev"],
  detachable: true
)

# Get the session ID from the message
session_id = receive do
  {:session_info, ^cmd, %{session_id: id}} -> id
end

# ... later, attach to it
{:ok, cmd} = Sprites.attach_session(sprite, session_id)

receive do
  {:stdout, ^cmd, data} -> IO.write(data)
end

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

Elixir

{:ok, sessions} = Sprites.list_sessions(sprite)
for session <- sessions do
  IO.puts("#{session.id}: #{session.command}")
end

---

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

Elixir

# Get sprite by name (doesn't verify it exists)
sprite = Sprites.sprite(client, "my-sprite")

# Get sprite and verify it exists
{:ok, sprite} = Sprites.get_sprite(client, "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,
    })
}

Elixir

# List all sprites
{:ok, sprites} = Sprites.list(client)

# List with prefix filter
{:ok, dev_sprites} = Sprites.list(client, prefix: "dev-")

# Iterate through sprites
for sprite <- sprites do
  IO.puts(sprite.name)
end

---

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)

Elixir

# Get sprite info including URL
{:ok, info} = Sprites.get_sprite(client, "my-sprite")
IO.puts(info.url)

# Update URL settings
Sprites.update_url_settings(sprite, public: true)

Updating URL settings is available via the CLI, Go SDK, Elixir 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},
})

Elixir

# Forward single port
{:ok, session} = Sprites.proxy_port(sprite, 3000, 3000)
# localhost:3000 now forwards to sprite:3000

# Forward multiple ports
mappings = [
  %Sprites.Proxy.PortMapping{local_port: 3000, remote_port: 3000},
  %Sprites.Proxy.PortMapping{local_port: 8080, remote_port: 80}
]
{:ok, sessions} = Sprites.proxy_ports(sprite, mappings)

# Stop proxy when done
Sprites.Proxy.Session.stop(session)

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

Elixir

{:ok, cmd} = Sprites.spawn(sprite, "npm", ["run", "dev"])

# Handle port notifications in receive loop
receive do
  {:port_opened, ^cmd, %{port: port, address: addr, pid: pid}} ->
    IO.puts("Port #{port} opened on #{addr} by PID #{pid}")

  {:stdout, ^cmd, data} ->
    IO.write(data)
end

---

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>

Elixir

# Create a checkpoint
{:ok, checkpoint} = Sprites.create_checkpoint(sprite, comment: "before deploy")

# List checkpoints
{:ok, checkpoints} = Sprites.list_checkpoints(sprite)

# Restore from checkpoint
{:ok, _} = Sprites.restore_checkpoint(sprite, 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())
    }
}

Elixir

case Sprites.cmd(sprite, "bash", ["-lc", "exit 1"]) do
  {_output, 0} ->
    IO.puts("Success")

  {output, exit_code} ->
    IO.puts("Exit code: #{exit_code}")
    IO.puts("Output: #{output}")
end

---

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

Elixir

:ok = Sprites.destroy(sprite)
# or
:ok = Sprites.destroy(client, "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 and examples

JavaScript SDK

Complete SDK reference for Node.js

Go SDK

Native Go integration mirroring os/exec

Elixir SDK

Idiomatic Elixir with Streams and message passing

Lifecycle & Persistence

Deep dive into how Sprites work

Networking

URLs, ports, and connectivity