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:

Surface	Client namespace	Use it for
Managed Research / Factory	`client.research`	Hosted research runs, projects, evidence, MCP (`synth-ai[research]`).
Containers	`client.containers`	Hosted container records and lifecycle operations.
Tunnels	`client.tunnels`	Managed tunnel records, leases, health, and rotation.
Pools	`client.pools`	Container pools, tasks, rollouts, artifacts, usage, and events.
CLI	`synth-ai`	Terminal access to containers, tunnels, and pools.

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

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).

synth-ai