Synth AI SDK

Python SDK and CLI for Synth infrastructure surfaces: tunnels, pools, and hosted containers.

Documentation: https://docs.usesynth.ai/sdk/overview

Installation

uv add synth-ai

Or install with pip:

pip install synth-ai

Authenticate

Set SYNTH_API_KEY before using the SDK or CLI:

export SYNTH_API_KEY="sk_..."

Local Workspaces

For local multi-repo development, synth-ai treats workspace resolution as a
read-only overlay. .env and Synth home config may provide defaults and
secrets; selecting a worktree must not rewrite those defaults.

Use SYNTH_WORKSPACE_MANIFEST or SYNTH_WORKSPACE_ROOT for command-scoped
worktree resolution. The resolver in synth_ai.core.utils.workspace returns
repo paths and a scoped env mapping for subprocesses without mutating .env.

Pass base_url when you need to pin a production, local, staging, or private
backend explicitly:

from synth_ai import SynthClient

client = SynthClient(base_url="http://127.0.0.1:8000")

The CLI also reads SYNTH_BACKEND_URL and accepts --backend-url.

Quickstart

from synth_ai import SynthClient

client = SynthClient()

print(client.containers.list())
print(client.tunnels.health())
print(client.pools.list())

CLI

synth-ai --help
synth-ai containers list
synth-ai tunnels health
synth-ai pools list

Public Surface

Use SynthClient as the front door:

Use Managed Research when you
want hosted research workers, repo runs, evidence, checkpoints, MCP, or final
reports.

Links

• Install and authenticate
• SynthClient guide
• Tunnels
• Pools
• Containers
• SDK reference
• OpenAPI contracts

Local Development

Use uv run for Python tools:

uv sync --group dev
uv run ruff format --check .
uv run ruff check .
uv run ty check

Optional: install Lefthook and run
lefthook install to run formatting, linting, and type checks on staged Python
files.

SMR Handoff X thread — hand agent tasks to Managed Research from Cursor, Codex, or Claude Code (repo).