A tunnel gives your agent a stable public hostname — {tunnel_name}.inkboxwire.com — that routes inbound HTTP, WebSocket, and raw-TCP traffic from third parties to your agent over a single persistent connection. Your agent stays behind whatever NAT, firewall, or laptop Wi-Fi it happens to be running on; no public IP, no firewall hole, no reverse proxy needed on your end.

Use the Python or TypeScript SDK to create tunnels and bring them online from your agent.

Pick a name and call inkbox.tunnels.create(...). The response includes a one-time connect_secret — store it securely; it is shown only once.

Tunnel names are 3–63 characters, lowercase letters / digits / hyphens, must start and end alphanumeric, no consecutive hyphens, and are globally unique within the environment.

The data-plane connect() helper opens the persistent agent connection and forwards inbound traffic to wherever you point it. The simplest setup forwards traffic to a local HTTP server you're already running.

The first call to connect() creates the tunnel if it doesn't already exist, persists the connect secret to a local state directory (default ~/.inkbox/tunnels/{name}), and opens the agent connection. Subsequent calls reuse the existing tunnel and the secret on disk. The TypeScript listener installs SIGINT and SIGTERM handlers automatically only when the parent process has none at construction time, so it stays out of the way of host processes that own their own shutdown — pass installSignalHandlers: false (or true to attach alongside) to override.

If you don't want to run a separate local HTTP server, hand connect() a handler function and it will run inside your agent process.

The ctx argument on the TypeScript handler exposes forwardedForIp, sniHost, an AbortSignal that fires when the runtime's deadline expires, and a read-only envelope escape hatch for metadata not surfaced on the typed fields.

Inbound WebSocket upgrades are bridged transparently to your handler.

connect() returns a TunnelListener. In Python, pick one lifecycle pair and stick with it — sync (wait / close) and async (serve_forever / aclose) are mutually exclusive on a given listener. In TypeScript, the listener is always async-driven; wait() is the canonical way to block until shutdown.

If you lose the secret or suspect it's been compromised, rotate it. The new secret takes effect on the agent's next reconnect; existing live connections keep serving traffic until they drop.

To cut over hard, restart your agent immediately after rotating.

delete() schedules removal: inbound traffic stops immediately and the tunnel enters a 24-hour grace window during which you can restore() it. After 24 hours the tunnel is removed and the name is released for re-use. SDK clients see this state as TunnelStatus.PENDING_REMOVAL; the wire shape returned by the REST API is delete_pending.

force_delete() finalizes a tunnel that's already in the grace window — call delete() first, then force_delete() to skip the remaining 24-hour wait. It returns 409 if the tunnel isn't pending removal, and requires an admin-scoped API key.

metadata is a free-form object capped at 4 KB serialized. It's returned as-is on read and is visible only within your org.

By default, Inkbox terminates TLS at our edge with a managed certificate. If your compliance posture or client-side cert pinning requires TLS to terminate inside your own process, use tls_mode="passthrough" and sign a CSR via inkbox.tunnels.sign_csr(...). See the Passthrough TLS reference for the full flow, including how connect() handles cert provisioning automatically when you pass tls_mode="passthrough".

• Tunnels API overview — REST endpoint summary
• Manage tunnels — CRUD endpoint reference
• Connect secret — rotation endpoint
• Passthrough TLS — CSR signing flow