# Tunnel — SDK & CLI > The clutchcall CLI surface: login, claim, http, p2p, devices, topup — plus config, env vars, and the data-plane engine flags. The tunnel modality is driven by the **`clutchcall` CLI** and its QUIC data-plane engine. There is no typed `Tunnel` SDK class today. > **NOTE:** > A programmatic client (embed a tunnel in your own process) is **Preview** — see > [Programmatic API (Preview)](#programmatic-api-preview) at the bottom. For > shipping work, use the CLI documented here. ## Install **One-liner:** ```sh curl -fsSL https://clutchcall.dev/clutchcall/install.sh | sh ``` **Homebrew / manual:** ```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 launches a separate QUIC engine for the data path; the engine ships next to the CLI or is pointed at with an env var (see [Config](#config)). ## Sign in ```sh clutchcall login # provider device flow — the provider hosts the UI ``` No credentials are stored. The CLI 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 ` | Remove a device, freeing a slot on the free plan | | `clutchcall claim ` | Reserve a subdomain → `https://.clutchcall.dev` | | `clutchcall http [--name n]` | Expose `localhost:` at a public HTTPS URL | | `clutchcall p2p share --port

` | Share a local service direct to a peer (no relay) | | `clutchcall p2p connect --listen

` | Reach a peer's shared service directly | | `clutchcall topup ` | Add wallet balance | | `clutchcall version` | Print version | --- ## `http` — expose a local service ```sh clutchcall http [--name ] [--slug ] ``` Dials the nearest edge PoP over QUIC and forwards inbound public traffic to `localhost:`. Prints the public URL and runs until interrupted. The local TCP port to expose (e.g. `3000`). A label appended to your reserved subdomain: with handle `alice`, `--name api` → `https://alice-api.clutchcall.dev`. Requires a claimed handle. Override the slug explicitly (power users). The edge still enforces your namespace from the session token, so a stale slug can't escape it. ```sh 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 ``` > **TIP:** > 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 auto-discover via the control-plane rendezvous and connect **directly**, with the edge brokering candidates but never carrying bytes. Across NATs, set the `

_STUN` env var (where `

` is your CLI's uppercased brand prefix) to a reflector so each side can gather its public candidate. **Share (the box with the service):** ```sh clutchcall p2p share --port [--proto tcp|udp|http] ``` **Connect (the box reaching in):** ```sh clutchcall p2p connect --listen ``` A shared secret both peers know; gates the direct tunnel and keys the rendezvous. (share) The local service port to expose to the peer. (connect) A local port to listen on; connections to it are piped to the peer's shared service. (share) `tcp`, `udp`, or `http`. STUN reflector `host:port` for reflexive candidate gathering (or set `

_STUN`). ```sh # 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 ``` > **NOTE:** > Endpoint-independent (cone) NATs punch through directly. Symmetric NATs fall back > to the relayed path. --- ## `status` & `devices` ```sh 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 caps you at 5 devices. Each install gets a stable device id, shown in `devices` and enforced by the session token's device claim. --- ## Config CLI state lives at your user config dir, e.g. `~/.config/clutchcall/config.json` (mode `0600`). It stores only non-secret session state: ```json { "api_base": "https://api.clutchcall.dev", "device_id": "dev-…", "device_name": "my-laptop", "token": "", "expires_at": "…", "handle": "alice" } ``` ### Environment variables Env vars use your CLI's brand prefix — shown below as `

` (the uppercased binary name, e.g. `clutchcall` → its uppercase form). | Var | Purpose | Default | | --- | --- | --- | | `

_API` | Control-plane base URL | `https://api.clutchcall.dev` | | `

_POP` | QUIC edge `host:port` (data plane) | `:4443` | | `

_STUN` | STUN reflector `host:port` for P2P | — | | `

_TUNNEL_BIN` | Path to the QUIC data-plane engine | next-to-binary / `$PATH` | | `

_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 it directly, but the surface is: ```sh clutchcall-engine http --server --token [--slug ] clutchcall-engine p2p share --quic-port

--peer --token [--stun ] clutchcall-engine p2p connect --quic-port

--peer --listen --token [--stun ] ``` --- ## 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. Enable it by pointing the client's `quic-relay-server` option at a `host:port` running 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 and never sees cleartext. This is the **remote-desktop tunnel type** in the [details page](/modalities/tunnel/details#tunnel-types); no extra CLI is needed beyond the relay endpoint. --- ## Programmatic API (Preview) > **WARNING:** > **Preview / forward-looking.** A typed `Tunnel` client to embed a tunnel inside > your own process is not in the shipping SDK. Ship with the CLI today. The shape > below is illustrative and may change. ```ts // 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(); ``` ```python # 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() ``` ## Related - [Tunnel overview](/modalities/tunnel/details) — wire model & architecture - [Cookbook](/modalities/tunnel/cookbook) — task snippets - [Recipes](/modalities/tunnel/recipes) — worked examples