API Reference¶

Tunnel Whisperer exposes two APIs: a REST/WebSocket 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¶

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,
  "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
}

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 zip file.

Relay management¶

Provision request body:

{
  "domain": "relay.example.com",
  "provider": "digitalocean",
  "token": "dop_v1_..."
}

User management¶

Create user request body:

{
  "name": "alice",
  "mappings": [
    { "client_port": 3389, "server_port": 3389 },
    { "client_port": 8443, "server_port": 443 }
  ]
}

Update user mappings request body:

{
  "mappings": [
    { "client_port": 3389, "server_port": 3389 },
    { "client_port": 8443, "server_port": 443 }
  ]
}

After updating, the user's authorized_keys entry is rewritten with new permitopen restrictions and a config outdated flag is set. The flag is cleared when the user's config bundle is downloaded.

Download response: application/zip binary with Content-Disposition header.

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:

event: status
data: {"mode":"server","server":{"state":"running",...}}

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

gRPC API¶

The gRPC API listens on port 50051 (configurable via server.api_port) and is used for CLI-to-daemon communication. When a daemon is running (via tw serve or tw dashboard), CLI commands like tw status, tw list users, and tw delete user connect to this API instead of reading state directly from disk.

Available RPC methods¶

The gRPC server starts automatically when running tw serve or tw dashboard.