Skip to main content
Sail ships a Python SDK (sail on PyPI) for Python 3.9+. It shares one engine with the TypeScript and Rust SDKs, so behavior matches across languages. This page covers install and Python-specific notes.

​
Install

pip install sail

uv add sail
Installing the Python SDK also puts the sail CLI on your PATH. To install the CLI on its own, see Install the CLI.

​
Configure

Set SAIL_API_KEY in the environment; the SDK also reads the credential sail auth login stores under ~/.sail. See Configuration.

​
Quickstart

import sail

# Look up (or create) the app your sandboxes belong to.
app = sail.App.find(name="example-app", mint_if_missing=True)

# Boot a sandbox.
sb = sail.Sailbox.create(app=app, name="worker-1")

# Run a command and stream its output.
proc = sb.exec("echo hello && ls /")
for chunk in proc.stdout:
    print(chunk, end="")
result = proc.wait()
print("exit code:", result.exit_code)

# Move files.
sb.write("/tmp/note.txt", "hi from the harness\n")
contents = sb.read("/tmp/note.txt")

# Lifecycle: pause / sleep / resume / checkpoint / terminate.
sb.terminate()

​
Sync and async

Every method that does I/O has an async twin under .aio (the interactive shell is sync-only), so the same surface works from scripts and from asyncio without blocking the event loop: 
sb = sail.Sailbox.create(app=app, name="box")
sb = await sail.Sailbox.create.aio(app=app, name="box")
See Sailbox → Sync and async for streaming and end-to-end examples.

​
Python-only features

  • @sail.function: decorate a local Python function and run it inside a Sailbox as if it were local.
  • Voyages and Inference: the agent flight recorder and attributed model calls.

​
Errors

Everything the SDK raises derives from sail.SailError, with Python builtins (ValueError, LookupError, TimeoutError, …) where they are the natural fit. See Errors.

​
API reference

For the complete class-by-class listing of the Sailbox surface (every method, parameter, and error type), see the Python SDK reference.