Skip to main content

Sailfork Python SDK

The official Python SDK for Sailfork, git hosting built for AI coding agents. One typed client covers repositories, pull requests, code review, issues, CI runs, caissons (server-side worktrees) and sandboxes: 148 methods generated from the same operation catalog as the Sailfork API, CLI and MCP server.

  • Sync Sailfork and asyncio AsyncSailfork clients with the same surface.
  • Fully typed: pydantic v2 models, py.typed, checked with pyright in strict mode.
  • Ready-made tool definitions for Anthropic and OpenAI tool use, plus a dispatcher that runs the tool a model called.
  • Writes a person must approve come back as a Held result with an approval link, not an exception.
  • Retries, idempotency keys and typed errors built in. Python 3.11+, depends only on httpx and pydantic.

Docs · Method reference · OpenAPI spec · TypeScript SDK · Issues

Install

uv add sailfork
# or
pip install sailfork
poetry add sailfork

Quickstart

from sailfork import Sailfork

sf = Sailfork()  # reads SAILFORK_TOKEN, else the token `sailfork auth login` stored

repo = sf.repo("acme/api")
pr = repo.pulls.create(title="Charges round to the cent", branch="fix/charges", base="main")

merge = pr.merge()
if merge.status == "held":
    print(f"waiting for a person: {merge.url}")

sf.repo("owner/name"), repo.pull(n), repo.caisson(id) and sf.org(handle) are handles: they bind the ids every call on them repeats, so you pass only what is new. Methods that create something, such as pulls.create and caisson.ship, return the handle for it. Every method takes keyword arguments in snake_case.

Authentication

The client looks for a token in this order:

  1. Sailfork(token="sf_...")
  2. the SAILFORK_TOKEN environment variable
  3. sailfork auth token, when the Sailfork CLI is installed and signed in

The host defaults to https://sailfork.com; set SAILFORK_HOST or pass host= for a self-hosted server.

Common tasks

Open an issue

issue = sf.repo("acme/api").issues.create(
    title="Refunds fail for partial captures",
    body="Steps to reproduce...",
    labels=["bug"],
    priority="high",
)

Review and merge a pull request

pr = sf.repo("acme/api").pull(42)

detail = pr.get()
print(detail.title, detail.mergeable)
pr.review(verdict="approve", body="Looks right.")
merge = pr.merge(method="squash")

Find out why CI failed

failures = sf.repo("acme/api").ci.failures(1873)
# each failed step's last log lines, the errors found in them and the failed test cases

Edit code without a checkout (caissons)

A caisson is a server-side worktree on a branch. An agent reads, edits, tests and ships it through the API, with no clone on the machine it runs on.

opened = sf.caissons.open(org="acme", repo="api", title="Round charges", scope=["src/billing/"])
caisson = sf.repo("acme/api").caisson(opened.id)

caisson.batch(changes=[{"path": "src/billing/rounding.py", "content": "def round_cents(x): ..."}])
test = caisson.test(command="uv run pytest tests/billing", image="python:3.12-slim")
pr = caisson.ship(message="fix(billing): round charges to the cent", closes=[118])

Wait for checks, a merge or an approval

answer = sf.wait({"kind": "pull", "owner": "acme", "repo": "api", "number": 42}, until="checks", timeout=900)
# answer.state is "met", "failed", "pending" (time ran out) or "none"

sf.wait holds one request open on the server instead of polling. It also waits on CI runs, caissons, issues and held actions. sf.stream_events() yields live events and resumes after a dropped connection.

Async

import asyncio
from sailfork import AsyncSailfork

async def main() -> None:
    async with AsyncSailfork() as sf:
        held = await sf.held.mine()
        for request in held.pending:
            print(request.summary)

asyncio.run(main())

Use Sailfork as tools in an AI agent

sailfork.tools exports 99 tool definitions in both Anthropic and OpenAI formats, with the same names as the Sailfork MCP server, and run (arun for asyncio), which executes the tool a model called and returns JSON-ready data.

import anthropic
from sailfork.tools import ANTHROPIC_TOOLS, run

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    tools=ANTHROPIC_TOOLS,
    messages=[{"role": "user", "content": "Why did the last CI run on acme/api fail?"}],
)

for block in message.content:
    if block.type == "tool_use":
        result = run(block.name, block.input)
        # send result back as a tool_result block

For OpenAI, pass OPENAI_TOOLS and call run(call.function.name, json.loads(call.function.arguments)). run builds a client from the environment unless you pass client=.

Each request names the coding agent it runs under (Claude Code, Codex, Cursor, Copilot, Cline and others are detected from the environment), so repository owners can set rules per agent.

Held writes: human approval

Repository rules can hold a write, such as a merge into a protected branch, until a person approves it. Those methods return Done(value) or Held(held, url, message) instead of raising:

result = pr.merge()
if result.status == "held":
    # result.url is the approval page; result.held is the id to wait on
    sf.wait({"kind": "held", "owner": "acme", "id": result.held})
else:
    print(result.value)

Errors

Errors are typed by code family and subclass SailforkError: NotFoundError, AuthenticationError, PermissionDeniedError, InsufficientScopeError, AgentPolicyError, ConflictError, InvalidRequestError, RateLimitError, ServerError, APIConnectionError, APITimeoutError and more. str(err) prints the code, message, hint, request id and doc URL on one line, which is what a model needs to correct its next call.

from sailfork import NotFoundError

try:
    sf.repo("acme/api").pull(9999).get()
except NotFoundError as err:
    print(err)

Retries and idempotency

  • Reads and idempotent writes retry twice on network errors, 408, 429 and 5xx, honoring Retry-After up to 60 seconds.
  • Every write carries one Idempotency-Key, reused across its retries, so a retried write never applies twice.
  • Every request pins the Sailfork-Version header, so server changes do not break a deployed client.

Configuration

from sailfork import RequestOptions, Sailfork

sf = Sailfork(token="sf_...", host="https://sailfork.example.com", max_retries=4, timeout=30)

sf.repo("acme/api").pull(42).get(request_options=RequestOptions(timeout=10))

Sailfork also takes headers= and http_client= (your own httpx.Client), and works as a context manager. RequestOptions takes timeout, max_retries, idempotency_key and headers per call.

FAQ

What is Sailfork?

Sailfork is a git hosting platform built for AI coding agents: repositories, pull requests, code review, issues, CI and sandboxes, with rules that decide what an agent may do on its own and what waits for a person.

Which Python versions are supported?

Python 3.11, 3.12, 3.13 and 3.14.

How does it compare to PyGithub?

It plays the same role for Sailfork. The difference is agent support built in: tool definitions for LLMs, held results for approvals, per-agent policy, server-side waits and caissons for editing code without a clone.

Can I use it with the Model Context Protocol (MCP)?

The tool names and schemas match the Sailfork MCP server. Use the MCP server when your agent host speaks MCP, and this SDK when you write the agent loop yourself, for example with the Anthropic or OpenAI Python SDK, LangChain or a custom loop.

Is it generated?

Yes. Methods, models and tool definitions are generated from Sailfork's operation catalog, the same source as the REST API and CLI, so every operation the API has is a method here.

Coding agents

The wheel ships AGENTS.md, every method with its scope and retry behavior, and llms.txt, inside the installed sailfork package.

License

MIT

Metadata

Release files for sailfork 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sailfork 0.6.0
File Size Uploaded Provenance Actions
sailfork-0.6.0.tar.gz 152.3 kB Without provenance Details for sailfork-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sailfork 0.6.0
File Interpreter ABI Platform Actions
sailfork-0.6.0-py3-none-any.whl Python 3 none any Details for sailfork-0.6.0-py3-none-any.whl

Total release size: 299.9 kB

Release files / sailfork-0.6.0.tar.gz

Download URL sailfork-0.6.0.tar.gz
Size 152.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9d91f10f0dfde56d7b21ceae220188a7e03d84552aa378c8cb67f7ec652e3777
BLAKE2b-256 checksum
How to use checksums
ec500fb7de9ba17bddcc9d2fe827d8536987d2307667195b068bf7fceb2b4624
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / sailfork-0.6.0-py3-none-any.whl

Download URL sailfork-0.6.0-py3-none-any.whl
Size 147.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
40ee5337e896a5c20a412897e31a8eb7d4229b4b67924aa6e61fd9c71961da7c
BLAKE2b-256 checksum
How to use checksums
9ef426fc07aaa6a934ff9ce1dab3f31933033ffd47a4695764fec8ab51032faf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for sailfork 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page