Python SDK

sdk/python is a thin client for tunneld's JSON-RPC protocol. It spawns tunneld as a subprocess and talks to it over a Unix domain socket via the standard library socket module — no third-party dependencies.

Windows note

socket.AF_UNIX support on Windows depends on your Python build — added for Windows in CPython 3.9, but not present in every official python.org Windows installer. Linux and macOS Python always have it. If TunnelClient.start() raises an AttributeError mentioning AF_UNIX, this is why — try a different Python distribution (e.g. from the Microsoft Store, or a recent python.org build) rather than assuming a code bug.

Install

cd sdk/python
pip install -e .

You also need a built tunneld binary on your PATH (or pass tunneld_path= explicitly):

go build -o tunneld ./cmd/tunneld

Usage

from tunnelcat_sdk import TunnelClient

with TunnelClient() as tc:
    result = tc.connect(
        server="https://your-control-server:443",
        username="you",
        password="secret",
    )
    print(result["socksAddr"])  # point any SOCKS5 client at this
    tc.disconnect()

Try it with zero real credentials

go run ./cmd/mockserver &
python examples/basic.py

API reference

`class TunnelError(Exception)`

Raised when tunneld returns an {"error": ...} response, or on a transport failure (timeout, socket closed).

`class TunnelClient`

Spawns tunneld and drives it over its Unix-socket JSON-RPC protocol. Supports the context-manager protocol (with TunnelClient() as tc: calls start() on entry, close() on exit).

TunnelClient(tunneld_path=None, socket_path=None, on_event=None, connect_timeout=5.0)

tunneld_path: Optional[str]: Explicit path to the tunneld binary. Defaults to searching PATH for tunneld (or tunneld.exe on Windows).
socket_path: Optional[str]: Explicit Unix socket path. Defaults to a random path under the system temp directory, one per instance.
on_event: Optional[Callable[[dict], None]]: Called from the background reader thread for every {"event": ...} line — see IPC events.
connect_timeout: float: Seconds to wait for the spawned process's socket file to appear before start() raises TunnelError.

start() -> None

Spawns tunneld -socket <socket_path>, waits up to connect_timeout for the socket file to appear, connects to it, and starts a daemon reader thread. Raises TunnelError if the binary can't be found, the process exits before creating its socket, or the wait times out.

connect(server: str, apikey: str = "", username: str = "", password: str = "", socks_addr: str = "", polling_only: bool = False) -> dict

Sends the IPC connect method and blocks for the result. Pass polling_only=True when talking to cmd/mockserver or any server without streaming support — see Wire Protocol.

disconnect() -> dict

Tears down the tunnel and local SOCKS5 listener.

status() -> dict

Current connection state — see IPC status for the result shape.

reconnect() -> dict

Re-authenticates with the same credentials passed to the last connect() call.

close() -> None

Closes the socket, terminates the tunneld subprocess (SIGTERM, then kill after a 5s grace period), and removes the socket file. Safe to call more than once. Called automatically on context-manager exit.