Crate sail 

sail-rs: the canonical, typed Sail SDK.

Client is the entry point: a cheap-to-clone async handle that owns configuration and transport (HTTP for lifecycle/app, gRPC for per-sailbox exec and file streams). Bindings (the Python extension, the TypeScript napi addon, and the CLI) are thin layers over it.

As a library, this crate documents its whole public API and never writes to the process streams or exits: callers decide how to surface output and errors.

The transport plumbing the 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 client::Client;

pub use client::ClientBuilder;

pub use sailbox::object::Sailbox;

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

Streaming exec engine: a running command in a sailbox with live output.

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 PTY bridge: the local terminal driven against a pty exec.

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.

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 Sailbox::write and Sailbox::write_stream. Default writes the file without creating missing parent directories and leaves its 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.