> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK

> The Sail Rust SDK for sailboxes: lifecycle, streaming exec, file transfer, and ingress from Rust

Sail ships a Rust SDK for sailboxes (`sail-rs` on crates.io). Create and drive
sailboxes from Rust: lifecycle, streaming exec, file transfer, and ingress.
This page covers install and Rust-specific notes.

## Install

```toml theme={null}
[dependencies]
sail-rs = "0.2"
# 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`:

```rust theme={null}
use sail::Client;
```

Adding the crate does not install the `sail` CLI (a library crate cannot ship a
companion binary). Install the CLI separately with
`curl -fsSL https://cli.sailresearch.com/install.sh | sh`.

## Configure

Set `SAIL_API_KEY` in the environment. The client
also falls back to the credential `sail auth login` stores under `~/.sail`,
the same configuration the CLI uses. Construct with `Client::from_env()`, or
use `Client::builder(api_key)` for explicit configuration.

## Quickstart

```rust theme={null}
use sail::exec::ExecOptions;
use sail::Client;

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

    // List the sailboxes in your org.
    let page = client.list_sailboxes(&Default::default()).await?;
    println!("{} sailboxes", page.items.len());

    // Bind one by id and run a command in it.
    let sb = client.sailbox("sb_...");
    let proc = sb
        .exec_shell("echo hello from the guest", ExecOptions::default())
        .await?;
    let result = proc.wait().await?;
    print!("{}", result.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

<Note>
  Voyages (agent tracing) and inference calls are currently Python-only; the
  Rust SDK covers the full sailbox surface. See the [Voyages
  reference](/voyages-sdk).
</Note>

`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`, streaming `exec` / `exec_shell`, file transfer
(one-shot `read` / `write`, streaming `read_stream` / `write_stream`),
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.

## API reference

For the complete listing of every type, method, parameter, and error, see the
[Rust SDK reference](/reference/rust-sdk), hosted on docs.rs.