tunnelcat-sdk

Build your own client on top of tunnelcat-server: language adapters for Python, Kotlin, C#, and Swift that spawn a small local daemon and drive it over JSON-RPC, plus a mock control/exit server so you can develop and test with zero real credentials or network access.

What this SDK is for

If you're building a new client application — desktop app, CLI tool, browser-extension backend, anything that needs to open a tunnel to a tunnelcat-server control node and relay traffic through it — this SDK gives you a five-language-wide, identical connect → status → disconnect API instead of reimplementing the wire protocol yourself. If you're implementing a compatible server, or writing an adapter for a language not listed here, start at Wire Protocol instead.

Quickstart (30 seconds, zero credentials)

cmd/tunneld and cmd/mockserver depend on tunnelcat-server's snc/core package via a local replace in go.mod, so clone that repo as a sibling directory literally named tunnel_cat first:

# 1. Clone both repos, sibling directories, exact name matters
git clone https://github.com/navlink-net/tunnelcat-server tunnel_cat
git clone https://github.com/navlink-net/tunnelcat-sdk
cd tunnelcat-sdk

# 2. Build the local daemon every non-iOS adapter drives
go build -o tunneld ./cmd/tunneld

# 3. Start a mock control/exit server — accepts ANY credentials, no network needed
go run ./cmd/mockserver &

# 4. Run any language's example against it
cd sdk/csharp/examples/Basic && dotnet run

This logs in against the mock, opens a local SOCKS5 proxy, checks its status, and disconnects — the same connect → status → disconnect flow every adapter follows, whichever language you pick. Swap sdk/csharp for sdk/python or sdk/kotlin's example once you have the matching toolchain — see each language page below.

Pick your language

Python

stdlib socket + subprocess. pip install -e .

Kotlin (JVM)

JDK 16+, desktop/server only — not Android.

C# / .NET

.NET 8, System.Net.Sockets.

Swift

macOS (subprocess) or iOS (linked archive) — two different mechanisms.

How it fits together

Every adapter is a thin process-and-socket wrapper — no tunnel logic lives in the SDK itself. It spawns cmd/tunneld (a small Go daemon built from this same repo) as a subprocess, and drives it over a newline-delimited JSON-RPC protocol on a local Unix domain socket. tunneld is the thing that actually holds tunnelcat-server's Authenticator/TunnelDialer/SOCKS5Server and speaks the real wire protocol to your control/exit server. See Architecture for the full picture, or jump straight to IPC Protocol for the exact JSON-RPC contract.

Path	What it is
`cmd/tunneld`	The subprocess every non-iOS adapter drives. Wraps tunnelcat-server's `Authenticator`/`TunnelDialer`/`SOCKS5Server` behind JSON-RPC over a Unix socket.
`cmd/mockserver`	Local mock control/exit implementing just enough of the wire protocol to test connect/disconnect/data-relay with zero real credentials.
`cmd/lib-ios`	iOS-only: a cgo `c-archive` export, linked directly into an app or extension (iOS forbids spawning subprocesses).
`sdk/python`, `sdk/kotlin`, `sdk/csharp`	Thin `tunneld` clients — subprocess + Unix socket JSON-RPC.
`sdk/swift/macOS`	Same shape as the three above.
`sdk/swift/ios`	Links `cmd/lib-ios` directly instead of spawning anything.
`docs/`	The protocol contracts this site is built from: `PROTOCOL.md` (wire format), `IPC.md` (tunneld's own contract), one quickstart per language.

License

Apache License 2.0, matching tunnelcat-server. Every SDK package (Python's pyproject.toml, C#'s .csproj) declares the same license — nothing here is dual-licensed.