API Reference¶

Tunnel Whisperer exposes two APIs: a REST/WebSocket/SSE API served by the dashboard for browser and HTTP clients, and a gRPC API for CLI-to-daemon communication.

REST API (Dashboard)¶

The dashboard HTTP server registers the endpoints listed below. All REST endpoints accept and return JSON unless noted otherwise.

Read-only¶

Contexts¶

Mode¶

Request body:

{ "mode": "server" }

Settings¶

Proxy request body:

{ "proxy": "socks5://host:1080" }

Log level request body:

{ "log_level": "debug" }

Server settings request body:

{
  "ssh_port": 2222,
  "api_port": 50051,
  "dashboard_port": 8080,
  "relay_ssh_port": 22,
  "relay_ssh_user": "ubuntu",
  "remote_port": 2222,
  "xray_port": 54001,
  "temp_xray_port": 59000
}

Only non-zero / non-empty fields are applied; omitted fields keep their current value.

Xray settings request body:

{
  "relay_host": "relay.example.com",
  "relay_port": 443,
  "path": "/tw"
}

Client settings request body:

{
  "ssh_user": "tunnel",
  "server_ssh_port": 2222,
  "xray_port": 54001,
  "listen_address": "127.0.0.1"
}

xray_port and listen_address are optional. listen_address sets the local interface forwarded tunnels bind to (0.0.0.0 to expose them on all interfaces).

Analytics settings request body:

{
  "enabled": true,
  "history_size": 720
}

Analytics changes take effect immediately — no restart required. The stats collector is created or destroyed on the fly.

Server control¶

Client control¶

Upload: POST /api/client/upload expects a multipart/form-data body with the bundle in a config file field (10 MB max).

Port override: POST /api/client/port-override takes a JSON body {"server_port": <int>, "local_port": <int>}, or {"server_port": <int>, "clear": true} to remove an override. Takes effect on next reconnect.

Relay management¶

Enrolled servers (relay mode only)¶

These endpoints mirror the tw relay … enrollment commands and answer only when the daemon runs in relay mode.

User management¶

There is no create or edit endpoint: users come to exist only through the interactive invite ceremony (tw server user invite), and their mappings are fixed at enrollment — changing them means deleting the user and inviting them again.

Application templates¶

Create/update application request body:

{
  "name": "web-app",
  "mappings": [
    { "client_port": 3000, "server_port": 3000 },
    { "client_port": 5432, "server_port": 5432 }
  ]
}

Application templates are reusable port mapping bundles. They are stored in config.yaml under server.applications and are not synced to the relay.

Server-Sent Events (SSE)¶

The {session_id} parameter identifies a browser session so multiple dashboard tabs can each receive events independently.

Event format — unnamed data: frames only (no event: field). Each frame is one ProgressEvent (or, on /api/logs, one log entry):

data: {"step":2,"total":5,"label":"Starting Xray","status":"running"}

Daemon status is polled via GET /api/status, not streamed.

gRPC API¶

The gRPC API listens on 127.0.0.1:50051 (loopback only; port configurable via server.api_port) and is used for CLI-to-daemon communication. It starts automatically with tw server start and tw dashboard. When a daemon is running, CLI commands like tw status and tw server user list connect to this API instead of reading state directly from disk.

Authentication¶

Loopback is not treated as an auth boundary: every RPC requires a per-daemon bearer token. The daemon generates a 32-byte token into a 0600 file (api.token in the config directory) on startup; the built-in client reads it from the same directory and attaches it as authorization: Bearer <token> metadata. A caller that cannot read the token file gets Unauthenticated, so a local process cannot overwrite keys or config, flip mode, delete users, or read secrets through the API merely by reaching loopback.

JSON codec — the proto is documentation only¶

The API uses the gRPC server machinery, but the wire format is JSON, not protobuf. A custom codec (registered under the content-subtype json) marshals hand-written Go structs directly, so no protoc-generated code is involved. The file proto/api/v1/service.proto exists as documentation only; make proto regenerates stubs that are not used on the wire. The service is registered as api.v1.TunnelWhisperer and every RPC is unary.

Clients must therefore dial with the JSON call option and attach the bearer token (the built-in client does: grpc.CallContentSubtype("json"), per-RPC token credentials over the plaintext loopback transport, 2-second dial timeout).

Service: api.v1.TunnelWhisperer¶

The CLI's built-in client wraps the subset it needs: GetStatus, TestRelay, ListUsers, DeleteUser, and DestroyRelay; every CLI command that can use the daemon falls back to local (on-disk) operation when no daemon answers on server.api_port. The invite flows (tw relay invite, tw server user invite, tw join) don't go through this API at all — they dial the relay directly over the Xray/SSH tunnel.