Tunnels

Manage Synth tunnel records and tunnel leases from the synth-ai SDK.

Tunnels expose local or managed services through backend-owned tunnel records and leases.

Python

from synth_ai import SynthClient

client = SynthClient()

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

Create a tunnel record:

tunnel = client.tunnels.create(
    subdomain="my-dev-service",
    local_host="127.0.0.1",
    local_port=8000,
)
print(tunnel)

Create a lease:

lease = client.tunnels.create_lease(
    client_instance_id="local-dev",
    local_host="127.0.0.1",
    local_port=8000,
    app_name="my-service",
    requested_ttl_seconds=3600,
)
print(lease)

Release the lease when finished:

client.tunnels.release_lease(lease["lease_id"])

CLI

synth-ai tunnels list
synth-ai tunnels create --subdomain my-dev-service --local-port 8000
synth-ai tunnels lease-create --client-instance-id local-dev --local-port 8000
synth-ai tunnels lease-release lease_123

Common errors

Symptom	What to check
401 or 403	Missing or wrong SYNTH_API_KEY.
Lease expires	Refresh the lease or request a longer TTL.
Local service unreachable	Check local_host, local_port, and service health.
Wrong backend	Set base_url in Python or SYNTH_BACKEND_URL for the CLI.