# Python client and sign-in

The arguments of Sailfork and AsyncSailfork, how the token and host are found, how to close a client, and the headers every request carries.

`Sailfork` is the synchronous client and `AsyncSailfork` the asyncio one. They take the same arguments, and every method on one has an awaitable twin on the other. In most programs the client is created with no arguments.

## Constructor arguments

```python
import httpx
from sailfork import Sailfork

sf = Sailfork()  # everything from the environment

sf = Sailfork(
    "sf_pat_...",
    host="https://sailfork.example.com",
    max_retries=4,
    timeout=httpx.Timeout(30.0, connect=5.0),
    headers={"X-Team": "payments"},
)
```

| Argument | Default | What it does |
| --- | --- | --- |
| `token` | none | The access token, the only positional argument. Found as [below](#token-and-host) when left out. |
| `host` | `https://sailfork.com` | The server address. A bare name gets `https://`, except `localhost` and `127.0.0.1`, which get `http://`. A trailing slash is dropped. Something that is not an address raises `ValueError`. |
| `max_retries` | `2` | How many times a failed call is tried again. See [Errors and retries](https://sailfork.com/docs/sdk-python-errors#retries-and-idempotency). |
| `timeout` | 60 seconds, 10 to connect | A number of seconds or an `httpx.Timeout`. |
| `headers` | none | Extra headers on every request. They override the ones the SDK sets, `Authorization` aside. |
| `http_client` | a new `httpx.Client` | Your own `httpx.Client` (`httpx.AsyncClient` for `AsyncSailfork`), for proxies, mounts and [tests](https://sailfork.com/docs/sdk-python-testing). The SDK does not close a client you pass. `timeout` applies to each request made through it. |

`sf.host` is the resolved address.

A call that waits on purpose, such as `caissons.ship`, `caissons.test`, `issues.start`, `sandboxes.exec` and `sf.wait`, sets its own request timeout of 85 seconds. That applies on a client you passed in as well.

## Token and host

The host is the first of these that holds an address: the `host` argument, `SAILFORK_HOST`, `SAILFORK_URL`, then `https://sailfork.com`.

The token is the first of these that holds one:

1. The `token` argument.
2. `SAILFORK_TOKEN`, but only when the resolved host is the one `SAILFORK_HOST` (or `SAILFORK_URL`, or the default) names. A client pointed at another host never sends it your environment's token.
3. The output of `sailfork auth token --host <host>`, run once with a 15 second limit, when `sailfork` or `sf` is on `PATH`.

The lookup happens at the first request and is remembered. The async client runs it in a thread. If nothing yields a token, no error is raised at that point. The request goes without credentials, which a public read allows and anything else answers with 401 `AuthenticationError`.

```python
from sailfork import Sailfork

Sailfork(host="localhost:8450")        # http://localhost:8450, token from the CLI for that host
Sailfork("sf_pat_...", host="acme.dev")  # https://acme.dev
```

A token on a client built with `host=` for another server comes from that server's CLI login or from the `token` argument, never from `SAILFORK_TOKEN`, unless `SAILFORK_HOST` points at the same server.

## Close the client

A client owns an HTTP connection pool. Use it as a context manager, or call `close()` (`await aclose()` on the async client). When you passed `http_client`, closing leaves it open.

```python
from sailfork import AsyncSailfork, Sailfork

with Sailfork() as sf:
    print(sf.held.mine().pending)

sf = Sailfork()
try:
    print(len(sf.held.mine().pending))
finally:
    sf.close()


async def main() -> None:
    async with AsyncSailfork() as sf:
        print((await sf.held.mine()).pending)
```

One `AsyncSailfork` is safe to share between tasks.

## Headers and agent naming

Every request carries these headers. Yours from `headers=` are added after them and can replace any but `Authorization`.

| Header | Value |
| --- | --- |
| `Accept` | `application/json`, or `text/event-stream` for the event stream |
| `Sailfork-Version` | `2026-12-01`, so a later API change does not break code written against this one |
| `User-Agent` | `sailfork-python/<version>` |
| `Authorization` | `Bearer <token>`, when there is a token |
| `X-Sailfork-Agent` | The coding agent the environment shows, such as `claude-code`. Left out when none is found. |
| `X-Sailfork-Session` | That agent's session id, when its environment has one |
| `Idempotency-Key` | On every call that changes something. See [retries](https://sailfork.com/docs/sdk-python-errors#retries-and-idempotency). |

The agent headers are how [agent permissions](https://sailfork.com/docs/agent-permissions) tell an agent from a person. The client reads them from environment variables of the tools it knows, and `SAILFORK_AGENT` overrides the guess:

```sh
SAILFORK_AGENT=release-bot python deploy.py   # names the agent
SAILFORK_AGENT=off python deploy.py           # sends no agent headers
SAILFORK_SESSION=nightly-42 python deploy.py  # sets the session
```

`SAILFORK_AGENT` also treats `0`, `none`, `false`, `no` and `null` as off, and `1` or `true` as the name `agent`.

Next to the TypeScript version of this page: [TypeScript client](https://sailfork.com/docs/sdk-typescript-client).

---

Every docs page: https://sailfork.com/llms.txt
