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::ImageFilesystem;

pub use image::ImageSpec;

pub use image::OciImage;

pub use sailbox::object::Sailbox;

pub use sailbox::object::SailboxFs;

pub use sailbox::ssh::EnableSshOptions;

pub use sailbox::ssh::SshEndpoint;

pub use sailbox::types::AutoSleep;

pub use sailbox::types::CheckpointOptions;

pub use sailbox::types::CreateSailboxRequest;

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 the Python and TypeScript SDKs and the 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 Sailbox’s localhost, so its own 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.