Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Tunnels
description: Teach your coding agent how to expose a local server at a public URL via Inkbox tunnels — CRUD, edge vs passthrough TLS, URL forwarding, and in-process handlers

---


# 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).

[View the source →](https://github.com/inkbox-ai/inkbox/tree/main/skills/inkbox-tunnels)

## 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

```bash
# via skills CLI (recommended)
npx skills add inkbox-ai/inkbox/skills

# manual (Claude Code)
git clone https://github.com/inkbox-ai/inkbox
cp -r inkbox/skills/inkbox-tunnels ~/.claude/skills/
```

## Prerequisites

- A POSIX host (Linux, macOS, or WSL) — `connect()` is not supported on Windows
- Python ≥ 3.11 with `pip install inkbox`, or Node.js ≥ 22 with `npm install @inkbox/sdk` (`@inkbox/sdk` declares `engines.node ">=22"` because the tunnels data-plane subpath imports `node:http2` and related Node-only modules)
- An [Inkbox](https://www.inkbox.ai) API key from the [Console](https://inkbox.ai/console/)