Skip to main content
A tunnel gives your agent a stable public URL — my-agent.inkboxwire.com — that routes inbound HTTP, WebSocket, and raw-TCP traffic from third parties to your agent over a single persistent connection. No public IP, firewall hole, or reverse proxy needed on your end. Every agent identity owns exactly one tunnel; the tunnel name always matches the identity’s handle. Tunnels are provisioned automatically when you create an identity and torn down when you delete it. The Tunnels API is read-mostly — list, get, update metadata, and (for passthrough) sign a CSR. API base URL:

​
Quick start

Create an account and get your API key from the Inkbox console:

Get API key

​
Tunnel naming rules

The tunnel name is always the identity’s agent_handle. Handles, and therefore tunnel names, are globally unique across all Inkbox customers.
  • 3–63 characters
  • lowercase letters, digits, and hyphens only
  • must start and end with a letter or digit
  • no consecutive hyphens
Some names are reserved; you’ll get a 409 if you pick one. See Manage identities for handle creation.

​
Lifecycle states

A live tunnel has one of two status values: The SDK enum members TunnelStatus.AWAITING_CERT and TunnelStatus.ACTIVE have the string values "awaiting_cert" and "active", matching the REST response.

​
TLS modes

Choose at creation time (via the nested tunnel.tls_mode on identity-create); immutable afterwards. See Passthrough TLS for the full passthrough flow.

​
Tunnel response fields

The tunnel object distinguishes two related host names:
  • public_host — per-tunnel public hostname (e.g. my-agent.inkboxwire.com). Use this for the public URL third parties hit.
  • zone — tunnel zone host (e.g. inkboxwire.com). The agent connects to https://{zone}/_system/connect here, not to https://{public_host}/_system/connect.
currently_connected reflects whether at least one agent connection is registered. last_disconnected_at is a best-effort timestamp of the most recently observed disconnect; use currently_connected for current liveness. last_connected_ip_addr captures the caller IP at the most recent /_system/hello. metadata is a customer-supplied free-form JSON object capped at 4 KB serialized.

​
Connecting your agent

The agent authenticates inbound connections on POST /_system/hello with two headers:
  • x-tunnel-id: <tunnel UUID> — which tunnel the agent is dialing.
  • x-api-key: <full API key> — the same REST API key the rest of the SDK uses.
Authorization rules:
  • An identity-scoped API key may connect a tunnel iff the tunnel’s owning identity matches the key’s scoped identity.
  • An admin-scoped API key may connect any tunnel in its org.
There is no per-tunnel secret. To rotate, rotate the customer’s API key. The Python and TypeScript SDKs ship a connect() helper that handles the persistent agent connection and graceful shutdown for you:
See the Tunnels capability guide for in-process handlers, WebSockets, and the full lifecycle.

​
Manage tunnels

List tunnels

List all tunnels in your organizationGET /api/v1/tunnels

Get tunnel

Get a single tunnel by ID, including live connection statusGET /api/v1/tunnels/{tunnel_id}

Update tunnel

Update metadata (name and TLS mode are immutable)PATCH /api/v1/tunnels/{tunnel_id}

​
Passthrough TLS

Sign CSR

Submit a CSR for a passthrough tunnel and receive a signed certPOST /api/v1/tunnels/{tunnel_id}/sign-csr

​
Additional resources