> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> The Sail Python SDK: install, sync and async, and Python-specific features

Sail ships a Python SDK (`sail` on PyPI) for Python 3.9+. It shares one
engine with the [TypeScript](/typescript-sdk) and
[Rust](/rust-sdk) SDKs, so behavior matches across languages. This
page covers install and Python-specific notes.

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install sail
  ```

  ```bash uv theme={null}
  uv add sail
  ```
</CodeGroup>

Installing the Python SDK also puts the `sail` CLI on your `PATH`. To install
the CLI on its own, see [Install the CLI](/cli).

## Configure

Set `SAIL_API_KEY` in the environment; the SDK
also reads the credential `sail auth login` stores under `~/.sail`. See
[Configuration](/sdk-configuration).

## Quickstart

```python theme={null}
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:

```python theme={null}
sb = sail.Sailbox.create(app=app, name="box")
sb = await sail.Sailbox.create.aio(app=app, name="box")
```

See [Sailbox → Sync and async](/sailbox-sdk#sync-and-async) for streaming and
end-to-end examples.

## Python-only features

* [`@sail.function`](/sailbox-sdk-images#sail-function): decorate a local
  Python function and run it inside a Sailbox as if it were local.
* [Voyages](/voyages-sdk) and [Inference](/voyages-sdk-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](/sailbox-sdk-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](/reference/python-sdk).