FAQ & Troubleshooting

Is there an Android SDK adapter?

No. The Kotlin adapter (sdk/kotlin) is explicitly JVM/desktop-only. Its own doc comment explains why: "An Android target would need an Android-sandbox-specific JNI fork/exec workaround (ProcessBuilder alone can't keep a TUN file descriptor open across exec on Android) that this adapter deliberately does not implement, since it's irrelevant off Android." If you're building an Android client, this SDK isn't the right starting point — you'd need a fork/exec workaround this repo doesn't provide, or a different integration approach entirely.

Why does my adapter need pollingOnly: true?

Because you're almost certainly testing against cmd/mockserver, which only implements the polling half of the wire protocol — streaming requests get a 404. Every SDK example sets pollingOnly: true for exactly this reason. Once you point at a production control/exit server with streaming support, you can drop the flag (or set it explicitly to false) to use the more efficient default.

Python: AttributeError mentioning AF_UNIX on Windows

socket.AF_UNIX support on Windows depends on your specific Python build — added for Windows in CPython 3.9, but not present in every official python.org Windows installer. Try a different distribution (a recent python.org build, or the Microsoft Store package) rather than assuming a code bug. Linux and macOS Python always have this.

"tunneld exited before creating its socket"

Every adapter raises some form of this error when the spawned tunneld process exits before its socket file appears — this usually means tunneld itself hit a startup error. Check its stdout/stderr (every adapter redirects them; check your process object/subprocess handle) rather than the SDK-level exception alone, which won't have the actual reason.

"timed out waiting for tunneld socket"

The process started but never created its socket file within connect_timeout (5 seconds by default in every adapter). Most commonly: wrong or missing -socket path permissions, or a stale socket file already at that path from a previous unclean shutdown blocking the bind. All adapters attempt to delete any pre-existing file at the socket path before spawning — if that's failing silently for you, check filesystem permissions on the temp directory.

What license is this under?

Apache License 2.0, matching tunnelcat-server. Every package manifest in the repo (Python's pyproject.toml, C#'s .csproj) declares the same license consistently.

Can I get a server-list / multi-server picker from this SDK?

No — this SDK's scope is strictly single-endpoint connect/status/disconnect/reconnect against a control server address you already have. A server-list/discovery API is a separate concern; see Architecture · What's out of scope for where that logic actually lives.

Where do I report a bug or ask a question?

github.com/navlink-net/tunnelcat-sdk — file an issue there. There's no separate support channel documented in the repo beyond GitHub issues.