Skip to main content
Sail ships SDKs for Python, TypeScript, and Rust. The Python SDK exposes three product surfaces from a single import sail:
  • Sailboxes: persistent Linux VMs you can create, run commands in, expose ports on, then checkpoint, pause, and resume.
  • Voyages: a flight recorder for long-running agents and background tasks. It records each run as a trace of nested agents, spans, and events. Python only.
  • Inference: model calls that automatically attribute themselves to the active Voyage. Python only.
For task-oriented walkthroughs, see the Sailboxes and Voyages guides.

​
Installation

pip install sail
# or: uv add sail

npm install @sailresearch/sdk
# or: pnpm add @sailresearch/sdk
# or: bun add @sailresearch/sdk

cargo add sail-rs
The Python SDK supports Python 3.9+ and also puts the sail CLI on your PATH; the TypeScript SDK supports Node 22+ and Bun. To install the CLI on its own, see Install the CLI. Language-specific setup notes live on the Python, TypeScript, and Rust pages.

​
Authentication

Every SDK reads your API key from the SAIL_API_KEY environment variable: 
export SAIL_API_KEY=sk_...
This is the recommended path for scripts, servers, and background agents, and it always takes precedence. If SAIL_API_KEY is unset, the SDKs fall back to the credential sail auth login stores under ~/.sail. Logging in once on your machine is enough for local scripts to authenticate without exporting anything. Sailbox and inference calls require a key from one of these sources. When none is found, sail.voyage is silently disabled (no Voyage is created and no network calls are made) so local scripts don’t crash; see the Voyages reference for details. See the Voyages reference environment table for the Voyage and agent attribution environment variables.

​
The sail surface (Python)

Everything you normally need is available directly on the top-level sail module:
SymbolWhat it is
sail.SailboxCreate and operate sailboxes. See Sailbox.
sail.AppThe org-owned application a Sailbox belongs to. See Apps.
sail.ImageBase images and the custom-image builder. See Images & Functions.
sail.functionDecorate a Python function to run it inside a Sailbox. See Images & Functions.
sail.voyageRecord agent and task runs. See Voyages.
sail.inferenceInference calls attributed to the active Voyage. See Inference.
sail.Config / sail.RetryPolicyEndpoint and retry configuration. See Configuration.
sail.SailTokenCompleter / sail.get_tinker_checkpoint_signed_url_asyncTinker RL/training integration. See Tinker.
sail.__version__ exposes the installed SDK version string.

​
Sync or async

The Python SDK ships a sync API and a matching async one: every method that does I/O has an async twin under .aio that you await (the interactive shell is sync-only). TypeScript and Rust are async-only. See Sailbox → Sync and async for streaming and end-to-end examples. 
sb = sail.Sailbox.create(app=app, name="box")
sb = await sail.Sailbox.create.aio(app=app, name="box")

​
Errors

Every SDK failure derives from a single base (SailError), so one handler catches everything, and specific types let you match individual failures. Each product narrows the tree further: Some calls also raise Python builtins (ValueError, LookupError, PermissionError, FileNotFoundError, TimeoutError) where that is the most natural fit; those are noted on the relevant method.