Kotlin SDK

sdk/kotlin is a thin client for tunneld's JSON-RPC protocol. It spawns tunneld via ProcessBuilder and talks to it over a Unix domain socket via java.nio.channels.SocketChannel + UnixDomainSocketAddress (JDK 16+).

This is not an Android adapter

This is a JVM/desktop adapter — don't assume "Kotlin" implies Android support. Android needs an Android-sandbox-specific JNI fork/exec mechanism (ProcessBuilder alone can't keep a TUN file descriptor open across exec on Android), which this adapter does not provide. See FAQ.

Build

cd sdk/kotlin
./gradlew build

You also need a built tunneld binary on your PATH:

go build -o tunneld ./cmd/tunneld   # from the repo root

Usage

import com.tunnelcat.sdk.TunnelClient
import com.tunnelcat.sdk.ConnectParams

val client = TunnelClient()
client.start()
val result = client.connect(ConnectParams(server = "https://your-control-server:443", username = "you", password = "secret"))
println(result?.getString("socksAddr"))
client.disconnect()
client.close()

Try it with zero real credentials

go run ./cmd/mockserver &

Then run src/main/examples/Basic.kt from your IDE (or wire it into a Gradle application/exec task) — it connects through the mock server and prints the resulting SOCKS5 address. ConnectParams(pollingOnly = true) is required against cmd/mockserver, which only implements the polling side of the wire protocol.

API reference

`class TunnelError(message: String) : Exception(message)`

Thrown when tunneld returns an {"error": ...} response, or on transport failure.

`data class ConnectParams`

ConnectParams( val server: String, val apiKey: String = "", val username: String = "", val password: String = "", val socksAddr: String = "", val pollingOnly: Boolean = false, )

pollingOnly: cmd/mockserver (and tunnelcat-server's own test stub) only support polling mode — see Wire Protocol.

`class TunnelClient(...) : AutoCloseable`

TunnelClient( tunneldPath: String? = null, socketPath: Path = <random temp path>, onEvent: ((JSONObject) -> Unit)? = null, connectTimeoutSeconds: Long = 5, )

Same parameters as the Python/C# adapters, JVM-idiomatic types. Constructor parameters are all private — configure everything at construction time.

fun start()

Spawns tunneld, waits for its socket, connects, and starts a daemon reader thread named tunnelcat-sdk-reader. Throws TunnelError on failure.

fun connect(p: ConnectParams): JSONObject?

Blocking call to the IPC connect method, up to a 15-second default timeout.

fun disconnect(): JSONObject?

fun status(): JSONObject?

fun reconnect(): JSONObject?

override fun close()

Closes the channel, destroys the tunneld process (force-kills after a 5-second grace period), and deletes the socket file.

Dependencies

org.json:json:20240303 — the only third-party dependency. Requires JDK 16+ for UnixDomainSocketAddress.