Crate sail 

sail-rs: the canonical, typed Sail SDK.

Client is the entry point: a cheap-to-clone async handle that owns configuration and connections. The Sail Python SDK, TypeScript SDK, and CLI are built on this crate.

As a library, this crate documents its whole public API and never writes to the process streams or exits, with one deliberate exception: Sailbox::shell bridges the caller’s terminal (raw mode, stdin/stdout, and a Ctrl-C handler) for the duration of the interactive session.

The plumbing the first-party bindings reach into lives under the hidden [internal] module; it is not part of the public API and carries no stability guarantee.

Re-exports

pub use app::App;

pub use client::Client;

pub use client::ClientBuilder;

pub use error::Result;

pub use error::RpcStatus;

pub use error::SailError;

pub use error::TransportKind;

pub use exec::CancelSignal;

pub use exec::ExecOptions;

pub use exec::ExecProcess;

pub use exec::ExecResult;

pub use exec::OutputStream;

pub use exec::RetryBudget;

pub use exec::RunOptions;

pub use exec::EXEC_CANCEL_RETRY;

pub use image::BaseImage;

pub use image::ImageArchitecture;

pub use image::ImageSpec;

pub use sailbox::object::Sailbox;

pub use sailbox::object::SailboxFs;

pub use sailbox::ssh::EnableSshOptions;

pub use sailbox::ssh::SshEndpoint;

pub use sailbox::types::CheckpointOptions;

pub use sailbox::types::CreateSailboxRequest;

pub use sailbox::types::ForkOptions;

pub use sailbox::types::IngressPort;

pub use sailbox::types::IngressProtocol;

pub use sailbox::types::ListSailboxesQuery;

pub use sailbox::types::ListenerEndpoint;

pub use sailbox::types::SailboxCheckpoint;

pub use sailbox::types::SailboxHandle;

pub use sailbox::types::SailboxInfo;

pub use sailbox::types::SailboxListOrder;

pub use sailbox::types::SailboxPage;

pub use sailbox::types::SailboxSize;

pub use sailbox::types::SailboxStatus;

pub use sailbox::types::SailboxStatusFilter;

pub use sailbox::types::VolumeMount;

pub use sailbox::types::WaitForListenerOptions;

pub use sailbox::DirEntry;

pub use sailbox::EntryType;

pub use sailbox::UpgradeResult;

pub use shell::ShellOptions;

pub use time;

Modules

app

Typed app discovery.

client

The Sail client: the canonical async surface that owns configuration and transport, shared by every binding (Python, TypeScript, CLI).

config

SDK configuration loaded from environment variables.

error

Canonical, language-neutral error taxonomy for the Sail core.

exec

A running command in a Sailbox with live output.

forward

Local port forwarding for interactive sessions. A PortForward listens on the user’s machine and forwards each accepted connection to the same port on the box’s localhost, so a sandbox’s localhost servers (dev servers, OAuth login callbacks) are reachable locally.

guest

Helpers for code running inside a Sailbox guest: the identity Sail injects at boot, and the metadata of mounted volumes. These read only local state (environment, kernel cmdline, mount metadata files) and fail with a clear error outside a guest.

image

Typed image specification for CreateSailboxRequest.

imagebuild

The custom-image build pipeline, shared by every SDK: resolve an ImageDefinition (walk local directories, hash files, upload content) into a content-addressed ImageSpec, then build it to ready.

sailbox

Typed Sailbox surface: domain models and the HTTP API client.

shell

Interactive terminal session against a pty command in a Sailbox.

Structs

FileReader

A streaming reader over a guest-file read response. A background task pumps chunks into a bounded channel (so a slow consumer applies backpressure rather than buffering the whole file); FileReader::next yields the next chunk, None at end of file. Dropping the reader cancels the download.

FileWriter

A streaming write to a guest file. Chunks feed a bounded channel that backs the client-streaming RPC, so a slow uplink applies backpressure rather than buffering the source. The RPC result surfaces from FileWriter::finish, and only finish commits the write: dropping (or FileWriter::aborting) an unfinished writer cancels the RPC instead of half-closing into what the server would treat as a completed write. The guest file state after an abort is unspecified (the write was never confirmed).

Listener

A Sailbox ingress listener, parsed from the sailbox-API listener JSON. The backend always sends the port, protocol, and route status; the public address fields are absent until the route is active.

WriteAbortHandle

Cancels a FileWriter’s RPC out of band. See FileWriter::abort for the semantics: only finish commits, and an aborted write reports the abort on later calls.

WriteOptions

Optional settings for SailboxFs::write and SailboxFs::write_stream. Default creates missing parent directories and leaves the file’s mode to the guest’s default.

Constants

FILE_WRITE_CHUNK_BYTES

Chunk size for streaming a file write: each FileWriter::write_chunk call becomes one gRPC message, so this keeps a chunk under the transport’s message limit. Bindings stream their source in pieces of this size.

Functions

block_on

Drive an SDK future to completion on the shared internal runtime, for synchronous callers outside any async context.

clear_notice_handler

Remove the process-wide notice callback. While no handler is installed, notices are dropped without consuming their once-per-process delivery, so a later notice of the same kind can still be delivered once a handler is reinstalled. Lets a full-screen TUI silence stderr notices while it owns the terminal without losing them for the rest of the process.

set_notice_handler

Replace the process-wide callback used for actionable notices returned by the Sail API. Each kind of notice (deprecated client build, deprecated Sailbox runtime) is delivered at most once per process.