Tunnels Skill
This skill teaches your coding agent how to bring a local server online at a public my-agent.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, and how to forward to a local URL or run an in-process Fetch / ASGI / WebSocket handler. Tunnels are provisioned and destroyed via the identity surface — every identity owns exactly one tunnel.
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 |
| 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; connect() requires POSIX and 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
