Skip to content

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

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"},
)
ArgumentDefaultWhat it does
tokennoneThe access token, the only positional argument. Found as below when left out.
hosthttps://sailfork.comThe 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_retries2How many times a failed call is tried again. See Errors and retries.
timeout60 seconds, 10 to connectA number of seconds or an httpx.Timeout.
headersnoneExtra headers on every request. They override the ones the SDK sets, Authorization aside.
http_clienta new httpx.ClientYour own httpx.Client (httpx.AsyncClient for AsyncSailfork), for proxies, mounts and tests. 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.

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.

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.

HeaderValue
Acceptapplication/json, or text/event-stream for the event stream
Sailfork-Version2026-12-01, so a later API change does not break code written against this one
User-Agentsailfork-python/<version>
AuthorizationBearer <token>, when there is a token
X-Sailfork-AgentThe coding agent the environment shows, such as claude-code. Left out when none is found.
X-Sailfork-SessionThat agent's session id, when its environment has one
Idempotency-KeyOn every call that changes something. See retries.

The agent headers are how 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:

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.

Loading Sailfork