inkbox-ai/inkbox/inkbox-tunnels

Inkbox Tunnels

Inkbox Tunnels expose a process running on the developer's machine (or any POSIX host) at a public https://{handle}.inkboxwire.com URL. The SDK opens an outbound HTTP/2 connection to the data plane; inbound third-party traffic rides back over that same connection. No inbound port to open, no static IP needed.

Tunnels are an identity property: every agent identity owns exactly one tunnel, and tunnel_name == agent_handle. There is no standalone "create tunnel" call — the tunnel is provisioned atomically by inkbox.createIdentity(...). Pre-existing identities created before this rollout already have tunnels (the migration backfilled them).

Two TLS modes:

Both modes accept either a `forward_to` URL (proxy to a local HTTP server) or an in-process callable (Fetch handler in TS, ASGI app in Python). WebSocket upgrades work on either.

Platform: the Python tunnel runtime supports Linux, macOS, and native Windows on Python 3.11+. WSL is not required. Keep Python updated to the latest patch release and store tunnel state in a private user directory. The Rust tunnel runtime requires POSIX.

Authentication

The data plane authenticates with the same API key the SDK client was constructed with. Two options:

• Admin-scoped key — can connect any tunnel in the org.
• Identity-scoped key — only valid for the tunnel attached to its scoped identity.

For a fresh agent bootstrap, mint an identity-scoped key after createIdentity:

identity = inkbox.create_identity("my-app")
scoped_key = inkbox.api_keys.create(label="my-app agent", scoped_identity_id=identity.id)
# Hand `scoped_key.api_key` to the agent process. Its `Inkbox(api_key=...)`
# will use it for both REST and the tunnel data plane.

The legacy per-tunnel connect_secret is gone — there is nothing to print, persist, or rotate per tunnel. To revoke a tunnel's access, revoke the API key.

The key is resolved in order: the api_key= argument → the INKBOX_API_KEY env var → a ~/.inkbox/config file (api_key = ...). The file fallback is handy for background/agent processes that don't inherit the shell's env. The CLI resolves the same way (--api-key → INKBOX_API_KEY → ~/.inkbox/config).

Python

Install

pip install inkbox

macOS note: the python.org installer doesn't hook into the system keychain, so TLS to the data plane can fail with SSL: CERTIFICATE_VERIFY_FAILED. The SDK now falls back to certifi's CA bundle automatically; if you still hit it, set export SSL_CERT_FILE=$(python -m certifi).

Forward to a local URL (edge mode)

from inkbox import Inkbox
with Inkbox(api_key="ApiKey_...") as inkbox:
    # Identity (with tunnel) must already exist — create it once:
    inkbox.create_identity("my-app")  # idempotent if you catch HandleUnavailableError
    listener = inkbox.tunnels.connect(
        name="my-app",
        forward_to="http://127.0.0.1:8080",
        # on_status may also report "superseded" after a newer client takes over.
        on_status=lambda s: print("tunnel:", s),
    )
    print(listener.public_url)   # https://my-app.inkboxwire.com
    listener.wait()              # blocks; Ctrl-C to stop

Subsequent runs read ~/.inkbox/tunnels/{name}/state.json for cached tunnel-id / zone / public-host. The state file no longer holds a secret.

Forward to an in-process ASGI app (FastAPI, Starlette, …)

from fastapi import FastAPI
from inkbox import Inkbox
app = FastAPI()
@app.get("/hello")
async def hello():
    return {"message": "hi from inkbox"}
with Inkbox(api_key="ApiKey_...") as inkbox:
    listener = inkbox.tunnels.connect(name="my-app", forward_to=app)
    listener.wait()

The runtime drives the ASGI app directly — no socket, no uvicorn needed. WebSocket scopes are supported the same way.

Passthrough TLS

inkbox.create_identity(
    "my-app",
    tunnel={"tls_mode": "passthrough"},
)
listener = inkbox.tunnels.connect(
    name="my-app",
    forward_to="http://127.0.0.1:8080",   # or an ASGI app
)

The tunnel's tls_mode is fixed at create time. In passthrough mode the SDK auto-generates and signs a certificate via the control plane (stored under ~/.inkbox/tunnels/{name}/). The third party connects directly to that cert.

Async usage

import asyncio
from inkbox import Inkbox
async def main():
    with Inkbox(api_key="ApiKey_...") as inkbox:
        listener = inkbox.tunnels.connect(name="my-app", forward_to="http://127.0.0.1:8080")
        try:
            await listener.serve_forever()
        finally:
            await listener.aclose()
asyncio.run(main())

wait()/close() and serve_forever()/aclose() are mutually exclusive — pick one pair.

Sample local liveness at any time with listener.status, listener.is_connected, and listener.last_connected_at. Status is idle, connecting, connected, reconnecting, closed, or superseded. The timestamp is an aware UTC datetime and remains available while reconnecting. These are local observations; listener.tunnel is the bootstrap resource snapshot. Status callbacks are edge-triggered and do not repeat reconnecting for each failed attempt in the same outage.

Control-plane reads + edit

inkbox.tunnels.list()                  # list[Tunnel]
inkbox.tunnels.get("tunnel-uuid")
inkbox.tunnels.update(                 # metadata-only
    "tunnel-uuid",
    metadata={"team": "gtm"},
)
# Passthrough only: sign a CSR
signed = inkbox.tunnels.sign_csr("tunnel-uuid", csr_pem=csr_bytes)

There is no create, delete, restore, force_delete, or rotate_secret here — tunnel lifecycle is owned by create_identity / identity.delete() (which cascades).

Common connect() options

TypeScript

Install

npm install @inkbox/sdk

Node ≥ 22, POSIX only. The data-plane subpath imports node:http2 / node:tls, so it's loaded from a separate entry — @inkbox/sdk itself stays browser-safe.

Forward to a local URL (edge mode)

import { Inkbox } from "@inkbox/sdk";
import { connect } from "@inkbox/sdk/tunnels/connect";
const inkbox = new Inkbox({ apiKey: process.env.INKBOX_API_KEY! });
await inkbox.createIdentity("my-app");  // once; the tunnel is provisioned atomically
const listener = await connect(inkbox, {
  name: "my-app",
  forwardTo: "http://127.0.0.1:8080",
});
console.log(listener.publicUrl);   // https://my-app.inkboxwire.com
await listener.wait();              // until Ctrl-C / SIGTERM

Sample local liveness with listener.status, listener.isConnected, and listener.lastConnectedAt. The same six states as Python are exposed. The timestamp remains set while reconnecting, and listener.tunnel remains the bootstrap resource snapshot. serveForever() and wait() both reject on terminal authentication, takeover, or unexpected fatal errors. Status callbacks are edge-triggered and do not repeat a state until it changes.

In-process Fetch-API handler

import { connect, type InkboxHandler } from "@inkbox/sdk/tunnels/connect";
const handler: InkboxHandler = async (req, ctx) => {
  if (new URL(req.url).pathname === "/hello") {
    return new Response(JSON.stringify({ message: "hi" }), {
      headers: { "content-type": "application/json" },
    });
  }
  return new Response("not found", { status: 404 });
};
const listener = await connect(inkbox, {
  name: "my-app",
  handler,
});
await listener.wait();

req is a standard Web Request; ctx exposes signal, forwardedForIp, sniHost, and the read-only envelope.

In-process WebSocket handler

import type { InkboxWsHandler } from "@inkbox/sdk/tunnels/connect";
const wsHandler: InkboxWsHandler = async (ws) => {
  await ws.accept();   // optionally { protocol, headers }
  for await (const msg of ws) {
    await ws.send(typeof msg === "string" ? `echo: ${msg}` : msg);
  }
};
const listener = await connect(inkbox, {
  name: "my-app",
  handler,        // HTTP fallback (any path that isn't a WS upgrade)
  wsHandler,      // every WS upgrade routes here
});
await listener.wait();

wsHandler requires either forwardTo or handler to be set as well — non-WS requests need a destination too.

Passthrough TLS

await inkbox.createIdentity("my-app", {
  tunnel: { tlsMode: "passthrough" },
});
const listener = await connect(inkbox, {
  name: "my-app",
  forwardTo: "http://127.0.0.1:8080",   // or pass `handler` / `wsHandler`
});

Control-plane reads + edit

await inkbox.tunnels.list();
await inkbox.tunnels.get("tunnel-uuid");
await inkbox.tunnels.update("tunnel-uuid", {
  metadata: { team: "gtm" },
});
// Passthrough only:
await inkbox.tunnels.signCsr("tunnel-uuid", { csrPem });

Tunnels are provisioned atomically by inkbox.createIdentity(...); there is no standalone create / delete / restore / forceDelete / rotateSecret surface.

For in-process WebSockets, catch WsServerDraining (4500) for planned handoff and WsConnectionLost (1011) for cold connection loss. Both extend WsClosed and set reconnectAdvised = true. URL-forwarded WebSockets receive the same close codes on the local upstream leg.

Common connect() options

Rust

Enable the tunnels-runtime feature. Rust keeps a blocking connect API and does not create an OS thread; run it on a caller-owned thread. A cloneable TunnelStatusHandle provides the same local states:

use inkbox::tunnels::client::TunnelStatusHandle;
 
let status = TunnelStatusHandle::new();
let runtime_status = status.clone();
let client = inkbox.clone();
let tunnel_thread = std::thread::spawn(move || {
    client.tunnels().connect_with_status(
        "my-app",
        "http://127.0.0.1:8080",
        runtime_status.callback(),
    )
});
 
let snapshot = status.snapshot();
println!("{:?} {:?}", snapshot.status, snapshot.last_connected_at);
 
// Join when shutdown is expected so bootstrap/runtime errors are surfaced.
if let Err(error) = tunnel_thread.join().expect("tunnel thread panicked") {
    eprintln!("tunnel stopped: {error}");
}