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, ingress, and credential injection. Behavior matches the Python and TypeScript SDKs.

Install

[dependencies]
sail-rs = "0.12.8"
# 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()
            },
        )
        .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

Hosted inference calls are Python-only. The Rust SDK covers the full Sailbox surface.

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 / set_auto_sleep / resume / upgrade), checkpoint, one-shot run / run_shell, streaming exec / exec_shell, filesystem helpers under fs() (one-shot read / write, streaming read_stream / write_stream, directory transfer upload_dir / download_dir, a signed download_url, and mkdir / remove / exists / ls), an interactive shell, listeners (expose / unexpose / listeners / listener / wait_for_listener / ingress_auth_headers), SSH (enable_ssh), and the egress policy (set_egress_policy / egress_policy).

run and run_shell return only the most recent output_buffer_bytes of each stream (1 MiB by default), with the *_truncated flags set when older output was dropped. To get every byte of a stream, use exec or exec_shell and take its reader (reader or reader_async) right after the call returns. Sail then pauses the command whenever the stream’s unread output fills its buffer, until a cancel or the timeout ends the pauses (see OutputMode). Dropping the reader releases the stream. A stream without a reader never pauses the command, and Sail keeps only its most recent bytes. ExecOptions::output_mode changes that: OutputMode::Pipe holds both streams until you take their readers, and OutputMode::Tail never pauses the command. You can read one stream without holding the other. If you hold both readers, read them concurrently from two tasks. The Exec process section has the details.

Org-scoped operations are methods on the Client: list_sailboxes, create_from_checkpoint, volumes, apps, the image build pipeline, secrets, and saved egress policies, which credential injection builds on.

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 documents 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.