Tunnel — SDK & CLI

The clutchcall CLI and its QUIC data-plane engine drive the tunnel modality. There is no typed Tunnel SDK class today.

A programmatic client, which embeds a tunnel in your own process, is Preview. See Programmatic API (Preview) at the bottom. For shipping work, use the CLI documented here.

Install

curl -fsSL https://clutchcall.dev/clutchcall/install.sh | sh

# Single static binary, no runtime deps — drop it on $PATH
clutchcall version

The CLI is a pure-static binary for Windows, macOS, and Linux (amd64 / arm64). It starts a separate QUIC engine for the data path. The engine ships next to the CLI, or you point at it with an env var (see Config).

clutchcall login      # provider device flow — the provider hosts the UI

The CLI stores no credentials. It persists only a short-lived session JWT and a device id under your user config dir (0600). Sign out with clutchcall logout.

Command surface

Command	What it does
`clutchcall login`	Sign in via device flow → session token
`clutchcall logout`	Forget the saved session
`clutchcall status`	Plan, devices (n/5), wallet balance, this-month egress
`clutchcall devices`	List your devices
`clutchcall devices rm <id>`	Remove a device to free a slot on the free plan
`clutchcall claim <name>`	Reserve a subdomain → `https://<name>.clutchcall.dev`
`clutchcall http <port> [--name n]`	Expose `localhost:<port>` at a public HTTPS URL
`clutchcall p2p share <pair-id> --port <p>`	Share a local service directly with a peer (no relay)
`clutchcall p2p connect <pair-id> --listen <p>`	Reach a peer’s shared service directly
`clutchcall topup <amount>`	Add wallet balance
`clutchcall version`	Print version

`http` — expose a local service

clutchcall http <local-port> [--name <sub>] [--slug <slug>]

The command dials the nearest edge PoP over QUIC. It forwards inbound public traffic to localhost:<local-port>. It prints the public URL and runs until you interrupt it.

int

required

The local TCP port to expose (e.g. 3000).

string

A label that the CLI appends to your reserved subdomain. With handle alice, --name api → https://alice-api.clutchcall.dev. It requires a claimed handle.

string

Set the slug explicitly (for power users). The edge still enforces your namespace from the session token, so a stale slug cannot escape it.

clutchcall claim alice          # reserve https://alice.clutchcall.dev
clutchcall http 3000            # → https://alice.clutchcall.dev
clutchcall http 8080 --name api # → https://alice-api.clutchcall.dev

WebSocket upgrades, server-sent events, and chunked/streaming responses pass through unchanged. Each public connection is its own QUIC stream.

`p2p` — direct peer-to-peer

Two peers run with the same pair-id. They discover each other through the control-plane rendezvous and connect directly. The edge brokers candidates but never carries bytes. Across NATs, set the <P>_STUN env var to a reflector, so each side can gather its public candidate. <P> is your CLI’s brand prefix in uppercase.

clutchcall p2p share <pair-id> --port <local-port> [--proto tcp|udp|http]

clutchcall p2p connect <pair-id> --listen <local-port>

string

required

A shared secret that both peers know. It gates the direct tunnel and keys the rendezvous.

int

(share) The local service port to expose to the peer.

int

(connect) A local port to listen on. The CLI pipes connections to it through to the peer’s shared service.

string

default:"tcp"

(share) tcp, udp, or http.

string

The STUN reflector host:port for reflexive candidate gathering. You can set <P>_STUN instead.

# Box A shares its SSH; Box B reaches it on its own port 8022
A$ clutchcall p2p share mylink --port 22
B$ clutchcall p2p connect mylink --listen 8022
B$ ssh -p 8022 localhost       # rides the direct QUIC link

Endpoint-independent (cone) NATs punch through directly. Symmetric NATs fall back to the relayed path.

`status` & `devices`

clutchcall status     # plan, devices (n/5), wallet balance, egress this month
clutchcall devices    # list devices; current device is marked
clutchcall devices rm dev-1a2b…   # free a slot

The free plan permits a maximum of 5 devices. Each install gets a stable device id. devices shows it, and the session token’s device claim enforces it.

Config

CLI state lives in your user config dir, for example ~/.config/clutchcall/config.json (mode 0600). It stores only non-secret session state:

{
  "api_base":    "https://api.clutchcall.dev",
  "device_id":   "dev-…",
  "device_name": "my-laptop",
  "token":       "<short-lived session JWT>",
  "expires_at":  "…",
  "handle":      "alice"
}

Environment variables

Env vars use your CLI’s brand prefix, shown below as <P>. The prefix is the binary name in uppercase, for example clutchcall → its uppercase form.

Var	Purpose	Default
`<P>_API`	Control-plane base URL	`https://api.clutchcall.dev`
`<P>_POP`	QUIC edge `host:port` (data plane)	`<base>:4443`
`<P>_STUN`	STUN reflector `host:port` for P2P	—
`<P>_TUNNEL_BIN`	Path to the QUIC data-plane engine	next-to-binary / `$PATH`
`<P>_BASE_DOMAIN`	Public base domain for printed URLs	`clutchcall.dev`

Data-plane engine flags

clutchcall http execs the QUIC engine (clutchcall-engine) with the resolved arguments. You rarely call the engine directly, but the surface is:

clutchcall-engine http <port> --server <pop> --token <jwt> [--slug <slug>]
clutchcall-engine p2p share <proto> <port> --quic-port <p> --peer <ip:port> --token <pair-id> [--stun <addr>]
clutchcall-engine p2p connect --quic-port <p> --peer <ip:port> --listen <port> --token <pair-id> [--stun <addr>]

Remote desktop on the same transport

A remote-desktop client (a fork of an open-source remote-desktop project) runs its network transport over this same raw-QUIC relay instead of its own rendezvous/relay. To enable it, point the client’s quic-relay-server option at a host:port that runs the tunnel module:

The controlled box registers its device id as a slug ("proto":"quick") and parks bidi work streams.
The controller dials the box by slug. The edge splices the two QUIC streams.
The remote-desktop client’s own message framing and end-to-end encryption ride unchanged on top. The edge only secures the QUIC hop to the PoP. It never sees cleartext.

This is the remote-desktop tunnel type in the details page. You need no extra CLI beyond the relay endpoint.

Programmatic API (Preview)

Preview / forward-looking. The shipping SDK does not contain a typed Tunnel client that embeds a tunnel inside your own process. Ship with the CLI today. The shape below is an illustration, and it can change.

TypeScript (Preview)
Python (Preview)

// Preview — not yet shipped
import { Tunnel } from "@clutchcall/sdk/tunnel";

const tunnel = new Tunnel({
  pop:   "edge.clutchcall.dev:4443",
  token: process.env.CLUTCHCALL_CREDENTIALS!,
});

const { url } = await tunnel.http({ port: 3000, slug: "alice" });
console.log("public URL:", url);   // https://alice.clutchcall.dev
await tunnel.close();

# Preview — not yet shipped
from clutchcall.tunnel import Tunnel

tunnel = Tunnel(pop="edge.clutchcall.dev:4443", token=TOKEN)
handle = tunnel.http(port=3000, slug="alice")
print("public URL:", handle.url)
tunnel.close()

Tunnel overview — wire model & architecture
Cookbook — task snippets
Recipes — worked examples

​Install

​Sign in

​Command surface

​http — expose a local service

​p2p — direct peer-to-peer

​status & devices

​Config

​Environment variables

​Data-plane engine flags

​Remote desktop on the same transport

​Programmatic API (Preview)

​Related

Install

Sign in

Command surface

`http` — expose a local service

`p2p` — direct peer-to-peer

`status` & `devices`

Config

Environment variables

Data-plane engine flags

Remote desktop on the same transport

Programmatic API (Preview)

Related