t-tunnel

A lightweight, terminal-based manager for Cloudflare Tunnels (cloudflared).

Browse your named tunnels, see live connection status, start/stop tunnels as managed background processes, create new tunnels, wire up DNS routes, and tail logs — all from one terminal screen.

Requirements

• Node.js >= 16
• cloudflared installed and on your PATH
• Already authenticated with cloudflared tunnel login (needed for list, create, delete, route dns)

Install

npm install
npm start

or, once published:

npx @ravishranjan/t-tunnel

Keybindings

| Key | Action | | -------------------- | ------------------------------------------------------- | | A | Create a new tunnel (cloudflared tunnel create) | | F | Find/filter tunnels by name or ID | | R | Run the selected tunnel as a managed background process | | X | Stop a tunnel started by this app | | N | Route a hostname to the selected tunnel (DNS) | | L | Toggle between details view and live log view | | Backspace/Delete | Delete the selected tunnel (with confirmation) | | Q / Ctrl-C | Quit (keeps managed tunnels running in background) |

How it works

• Listing & status — polls cloudflared tunnel list -o json every few seconds for the full tunnel inventory, including each tunnel's active edge connections (grouped by data-center, e.g. 2xDFW, 1xLHR), exactly as cloudflared reports them.
• Running tunnels — Cloudflare Tunnels aren't necessarily systemd units, so instead of shelling out to systemctl, t-tunnel starts cloudflared tunnel run <name> as a detached background process and persists its PID/state under ~/.t-tunnel/. This keeps tunnels alive across app closes or terminal exits. X sends SIGTERM (then SIGKILL if needed). Logs are written to ~/.t-tunnel/logs/ and viewable with L, including after reopening the app.
• Tunnel sources are exclusive — API/account tunnels and config-file tunnels are shown as separate entries ([api] vs [config]), even if they refer to the same tunnel identifier.
• Config-file list persists — config files loaded with C are saved under ~/.t-tunnel/config-files.json and reloaded on next launch.
• A tunnel with active connections but not started by this app shows as connected (green) rather than running — it's live, but managed elsewhere (e.g. a system service, Docker container, or another terminal).
• Create/Delete/Route DNS shell out to cloudflared tunnel create|delete|route dns respectively.

Project layout

• index.js — application state, keybindings, event wiring
• ui.js — blessed widget definitions (list, details pane, footer, input/search/confirm dialogs)
• cloudflared.js — thin wrapper around the cloudflared CLI plus local process tracking for tunnels started by this app
• formatters.js — display helpers (relative timestamps, connection summaries, error formatting)

License

GPL-2.0