Crate sprites 

Sprites SDK for Rust

Official Rust client for the Sprites API - stateful sandbox environments from Fly.io.

Sprites are lightweight, persistent VMs powered by Firecracker. They hibernate when idle (no compute cost) and wake instantly when needed. Create checkpoints in ~300ms and restore to any previous state.

Quick Start

use sprites::SpritesClient;

#[tokio::main]
async fn main() -> sprites::Result<()> {
    // Create a client with your API token
    let client = SpritesClient::new(std::env::var("SPRITES_TOKEN").unwrap());

    // Create a sprite
    let sprite = client.create("my-sprite").await?;

    // Run a command
    let output = sprite.command("uname").arg("-a").output().await?;
    println!("{}", output.stdout_str());

    // Create a checkpoint
    let checkpoint = sprite.checkpoint("Initial state").await?;
    println!("Checkpoint: {}", checkpoint.id);

    // Clean up
    sprite.destroy().await?;

    Ok(())
}

Command Execution

The Command struct mirrors std::process::Command:

use sprites::SpritesClient;

let client = SpritesClient::new("token");
let sprite = client.sprite("my-sprite");

let output = sprite
    .command("npm")
    .arg("install")
    .current_dir("/app")
    .env("NODE_ENV", "production")
    .output()
    .await?;

if output.success() {
    println!("stdout: {}", output.stdout_str());
}

For long-running processes, use Command::spawn for streaming I/O:

use sprites::SpritesClient;

let client = SpritesClient::new("token");
let sprite = client.sprite("my-sprite");

let mut child = sprite.command("npm").arg("run").arg("dev").spawn().await?;

// Wait for completion and get output
let status = child.wait().await?;
println!("Process exited with: {:?}", status);

Checkpoints

Create snapshots for instant rollback (~300ms):

use sprites::SpritesClient;

let client = SpritesClient::new("token");
let sprite = client.sprite("my-sprite");

// Create a checkpoint before risky operations
let checkpoint = sprite.checkpoint("Before migration").await?;

// Run migrations...
sprite.command("npm").arg("run").arg("migrate").output().await?;

// If something goes wrong, restore instantly
sprite.restore(&checkpoint.id).await?;

Network Policies

Control what domains your sprite can access:

use sprites::{SpritesClient, NetworkPolicy, NetworkPolicyRule, PolicyAction};

let client = SpritesClient::new("token");
let sprite = client.sprite("my-sprite");

let policy = NetworkPolicy {
    rules: vec![
        NetworkPolicyRule {
            domain: "api.anthropic.com".into(),
            action: PolicyAction::Allow,
        },
        NetworkPolicyRule {
            domain: "*.npmjs.org".into(),
            action: PolicyAction::Allow,
        },
        NetworkPolicyRule {
            domain: "*".into(),
            action: PolicyAction::Deny,
        },
    ],
    include: vec![],
};

sprite.set_policy(policy).await?;

Feature Flags

This crate uses rustls for TLS by default. All async operations require a Tokio runtime.

Structs

AttachCommand

A command to attach to an existing session

Checkpoint

Checkpoint information

Child

A handle to a running command in a sprite

ChildStderr

Handle for reading from a child’s stderr

ChildStdin

Handle for writing to a child’s stdin

ChildStdout

Handle for reading from a child’s stdout

Command

A command to execute in a sprite

DirEntry

Entry in a directory listing

ExecOptions

Execution options for commands

ExitStatus

Exit status from a command

FileInfo

Information about a file

Filesystem

Handle for filesystem operations on a sprite

ListCheckpointsOptions

Options for listing checkpoints

ListCheckpointsResponse

Response from listing checkpoints

ListOptions

Options for listing sprites

ListSpritesResponse

Response from listing sprites

NetworkPolicy

Network policy configuration

NetworkPolicyRule

Network policy rule

Output

Command output

PortMapping

A mapping from a local port to a remote port

ProxySession

An active proxy session forwarding traffic to a sprite

ServiceLogEntry

A log entry from a service

ServiceLogStream

Stream of service log entries

ServiceRequest

Request to create or update a service

ServiceState

Current state of a service

Session

Active execution session

SessionInfo

Information about an active session

Sprite

Handle to a sprite

SpriteConfig

Sprite configuration

SpriteInfo

Full sprite information returned by the API

SpritesClient

Sprites API client

SpritesClientBuilder

Builder for configuring a SpritesClient

UrlSettings

URL settings for a sprite

Version

Server version information

Enums

Error

Errors that can occur when interacting with the Sprites API

PolicyAction

Network policy action

ServiceStatus

Service status

Signal

Unix signal to send to a service

SpriteStatus

Sprite status

StreamMessage

Streaming message types for checkpoints and exec

UrlAuth

URL authentication settings

Type Aliases

Result

Result type alias for Sprites operations