Rust SDK

Rust SDK installation and API reference on docs.rs

The Sail Rust SDK (sail-rs on crates.io) creates and drives Sailboxes from Rust: lifecycle, streaming exec, file transfer, and ingress. It shares one engine with the Python and TypeScript SDKs, so behavior matches across languages.

Install

[dependencies]
sail-rs = "0.4"
# tokio must be a direct dependency to write #[tokio::main]:
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The crate is published as sail-rs and imported as sail:

use sail::Client;

Adding the crate does not install the sail CLI. Install the CLI separately with curl -fsSL https://cli.sailresearch.com/install.sh | sh, or see Install the CLI.

Configure

Set SAIL_API_KEY in the environment; the SDK also reads the credential sail auth login stores under ~/.sail. Construct with Client::from_env(), or use Client::builder(api_key) for explicit configuration. See Configuration.

Quickstart

use sail::{Client, CreateSailboxRequest, RunOptions, SailError};

#[tokio::main]
async fn main() -> Result<(), SailError> {
    let client = Client::from_env()?;

    // Look up (or create) the app your Sailboxes belong to.
    let app = client
        .find_app("rust-quickstart", /* mint_if_missing */ true)
        .await?;

    // Create a Sailbox; the default request uses the prebuilt Debian base image.
    let sb = client
        .create_sailbox(
            &CreateSailboxRequest {
                app_id: app.id,
                name: "quickstart".into(),
                ..Default::default()
            },
            /* timeout */ None,
        )
        .await?;

    // Run a command, then terminate the Sailbox whether or not the run failed.
    let run = sb
        .run_shell("echo hello from the guest", RunOptions::default())
        .await;
    sb.terminate().await?;

    print!("{}", run?.stdout);
    Ok(())
}

Runtime

Every method is async, driven on a Tokio runtime. Async hosts await the methods directly. Synchronous code can drive any method with sail::block_on, which runs it to completion on a shared internal runtime. Client is cheap to clone (it shares its connection pools and config behind an Arc), so clone it to share across tasks.

Surface

Voyages (agent tracing) and inference calls are Python-only; the Rust SDK covers the full Sailbox surface. See the Voyages reference.

create_sailbox and create_from_checkpoint return a Sailbox, and client.sailbox(id) binds an existing id without a network call. Every per-Sailbox operation is a method on it: lifecycle (info / terminate / pause / sleep / resume / upgrade), checkpoint, fork, one-shot run / run_shell, streaming exec / exec_shell, filesystem helpers under fs() (one-shot read / write, streaming read_stream / write_stream, and mkdir / remove / exists / ls), an interactive shell, listeners (expose / unexpose / listeners / listener / wait_for_listener / ingress_auth_headers), and SSH (enable_ssh).

Org-scoped operations live on the Client: list_sailboxes, create_from_checkpoint, volumes, apps, and the image build pipeline.

Volumes are currently in Alpha. To pilot them, reach out in the Sail Slack.

API reference

The full API reference is generated by rustdoc and published on docs.rs. It covers every module, type, and method in the crate, with source links and cross-references.

sail-rs on docs.rs

Open the complete sail-rs reference.