> ## 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

> 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](/reference/python-sdk) and
[TypeScript](/reference/typescript-sdk) SDKs, so behavior matches across
languages.

## Install

```toml theme={null}
[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`:

```rust theme={null}
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](/reference/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](/reference/sdk-configuration).

## Quickstart

```rust theme={null}
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

<Note>
  Voyages (agent tracing) and inference calls are 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`, `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.

<Note>
  Volumes are currently in Alpha. To pilot them, reach out in the [Sail
  Slack](https://join.slack.com/t/sailresearchcrew/shared_invite/zt-41pdcym9j-UU0Ey~A~r6n2H0DQVQsQHQ).
</Note>

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

<Card title="sail-rs on docs.rs" icon="rust" href="https://docs.rs/sail-rs">
  Open the complete `sail-rs` reference.
</Card>