| Connect (Python) | inkbox.tunnels.connect(name=..., forward_to=...) — returns a TunnelListener; wait() / close() for sync, serve_forever() / aclose() for async |
| Connect (TypeScript) | import { connect } from "@inkbox/sdk/tunnels/connect" — Node-only subpath; returns Promise<TunnelListener>; await listener.wait() to block until shutdown |
| URL forwarding | Pass forward_to (Python) or forwardTo (TS) — defaults to loopback-only; opt into remote forwarding only after reviewing the SSRF tradeoff |
| In-process handler (TS) | Fetch-API (req, ctx) => Response | Promise<Response> — ctx exposes signal, forwardedForIp, sniHost, and the read-only envelope |
| In-process handler (Python) | Pass an ASGI app callable as forward_to — works with FastAPI, Starlette, or any ASGI 3.0 framework; WebSocket scopes supported |
| WebSocket handler (TS) | wsHandler: async (ws) => { await ws.accept(); for await (const msg of ws) { ... } } — paired with an HTTP path |
| Edge vs passthrough TLS | Default edge — Inkbox terminates TLS at the edge. passthrough — your process terminates TLS; SDK auto-generates and signs the cert via the control plane |
| Provisioning | Tunnels are provisioned by inkbox.create_identity(...) / inkbox.createIdentity(...) — pass nested tunnel: { tls_mode } to customize. Read the tunnel back off identity.tunnel |
| Read-only API (Python) | list / get / update / sign_csr |
| Read-only API (TypeScript) | list / get / update / signCsr |
| Lifecycle | Deletion flows through identity.delete() — the linked tunnel is torn down with it. No grace window, no restore. TunnelStatus is AWAITING_CERT / ACTIVE |
| Data-plane auth | The data-plane hello carries x-tunnel-id (tunnel UUID) and x-api-key (the same REST key the rest of the SDK uses). No per-tunnel secret on disk |
| Common options (Python) | pool_size (1–32), on_status callback (connecting / connected / reconnecting / closed), body caps |
| Common options (TypeScript) | poolSize (1–32), onStatus callback, body caps, installSignalHandlers for clean shutdown (auto-installs only when no SIGINT/SIGTERM handlers are present) |
| Platform notes | Control-plane operations (list / get / update / sign_csr) work everywhere. Python connect() runs on Linux, macOS, and native Windows (SDK 0.7.4+, no WSL required). TypeScript connect() and the Rust runtime require POSIX |
