Tunnels Skill
This skill teaches your coding agent how to bring a local server online at a public {name}.inkboxwire.com URL using Inkbox tunnels. Once installed, the agent knows how to call inkbox.tunnels.connect(...) in either Python or TypeScript, when to pick edge vs passthrough TLS, how to forward to a local URL or run an in-process Fetch / ASGI / WebSocket handler, and how to manage the tunnel lifecycle (create, list, delete, restore, rotate secret).
What your agent learns
| Feature | Operations |
|---|---|
| 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 |
| CRUD (Python) | list / get / create / update / delete / restore / force_delete / rotate_secret / sign_csr |
| CRUD (TypeScript) | list / get / create / update / delete / restore / forceDelete / rotateSecret / signCsr |
| Lifecycle | delete() enters a 24-hour grace window; restore() un-deletes within it; force_delete() / forceDelete() finalizes a tunnel already in the grace window (call delete() first); connect() auto-restores PENDING_REMOVAL tunnels by default. SDK exposes status as TunnelStatus.PENDING_REMOVAL; the wire shape is delete_pending |
| Connect secret | Returned once at create — persisted to ~/.inkbox/tunnels/{name}/state.json. If lost, rotate via rotate_secret(id) / rotateSecret(id) and pass secret=... on next connect |
| State directory | ~/.inkbox/tunnels/{name} (0700). Holds connect secret and, in passthrough mode, the private key. Treat it like an SSH key dir |
| 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 | Tunnels require POSIX. CRUD works everywhere; connect() raises on Windows |
Install
bashPrerequisites
- A POSIX host (Linux, macOS, or WSL) —
connect()is not supported on Windows - Python ≥ 3.11 with
pip install inkbox, or Node.js ≥ 22 withnpm install @inkbox/sdk(@inkbox/sdkdeclaresengines.node ">=22"because the tunnels data-plane subpath importsnode:http2and related Node-only modules) - An Inkbox API key from the Console