Skip to main content
The Sail Python SDK (sail-sdk) is the client library for Sail. It exposes three product surfaces from a single import sail:
  • Sailboxes — persistent Linux VMs you create, run commands in, expose ports from, and checkpoint/pause/resume.
  • Voyages — a flight recorder for long-running agent and background-task trajectories.
  • Inference — thin wrappers over Sail’s hosted inference endpoints that correlate model calls with the active Voyage.
This Reference documents the SDK’s public Python surface. For task-oriented walkthroughs, see the Sailboxes and Voyages guides.

​
Installation

Install with pip: 
pip install "sail-sdk>=0.1.39"
Or with uv: 
uv add sail-sdk
The SDK targets Python 3.11+.

​
Authentication

Set your API key in the environment before using the SDK: 
export SAIL_API_KEY=sk_...
Sailbox and inference calls require SAIL_API_KEY. When it is absent, sail.voyage degrades to a safe no-op (no Voyage is created and no network calls are made) so local scripts don’t crash; see the Voyages reference for details. SAIL_MODE selects the environment the SDK talks to (prod by default; dev and staging are also valid). See the Voyages reference environment table for the full list of supported environment variables.

​
The sail surface

Everything you normally need is available directly on the top-level sail module:
SymbolWhat it is
sail.SailboxCreate and operate sandbox VMs. 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/task trajectories. See Voyages.
sail.inferenceVoyage-correlated inference wrappers. 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.

​
Errors

All SDK exceptions derive from a single base, sail.SailError, so you can catch everything the SDK raises with one except sail.SailError. 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.