Skip to main content

​
List Active Tunnels

View all your currently active tunnels: 
rs-tunnel list
Example output: 
7c9f2e1a-4b8d-4e3f-9a7c-8d5e2f1a9b3c | my-app.tunnel.example.com | status=active | port=3000 | created=2026-03-05T10:30:15.123Z
9d3e5f8b-7c4a-4f9e-8b2d-6e3f5a8c7d1e | test.tunnel.example.com | status=active | port=8080 | created=2026-03-05T11:45:22.456Z
Output format: 
<tunnel-id> | <hostname> | status=<status> | port=<port> | created=<timestamp>
If you have no active tunnels, the command displays: No active tunnels.

​
Stop a Tunnel

Stop an active tunnel using either its tunnel ID or hostname: 
rs-tunnel stop 7c9f2e1a-4b8d-4e3f-9a7c-8d5e2f1a9b3c
Success output: 
Stopped tunnel 7c9f2e1a-4b8d-4e3f-9a7c-8d5e2f1a9b3c
Stopping a tunnel:
  • Removes the DNS record
  • Deletes the Cloudflare tunnel
  • Makes the hostname available for reuse

​
Logout

Invalidate your session and clear stored credentials: 
rs-tunnel logout
Output: 
Logged out.
This command:
  • Revokes your access and refresh tokens on the server
  • Clears locally stored credentials (from keytar or encrypted file storage)
  • Requires you to log in again before creating new tunnels
Logging out does not stop your active tunnels. Stop them explicitly with rs-tunnel stop before logging out.

​
Diagnostic Check

Verify your rs-tunnel installation and environment: 
rs-tunnel doctor
Example output: 
OS: linux x64 (supported)
API (https://api.example.com): reachable
Auth session: present ([email protected])
cloudflared: found at /home/user/.rs-tunnel/bin/cloudflared (2024.12.0)

​
What doctor Checks

Operating System

Verifies you’re on a supported platform:
macOS, Linux, or Windows

API Connectivity

Tests connection to the configured API server
Shows the API URL being used

Authentication

Checks if you have a valid session
Shows the authenticated email

Cloudflared Binary

Verifies cloudflared is installed
Shows path and version
Run rs-tunnel doctor when troubleshooting connection issues or verifying your setup after installation.

​
Tunnel Lifecycle

​
Active Tunnel States

Tunnels can be in the following states:
  • active: Tunnel is running and receiving heartbeats
  • stale: Tunnel stopped sending heartbeats (will be cleaned up)

​
Heartbeat Mechanism

While a tunnel is running:
  1. CLI sends heartbeat every 20 seconds (default)
  2. Server updates the tunnel’s last heartbeat timestamp
  3. If no heartbeat received for 60 seconds (default), tunnel is marked stale
  4. Reaper process cleans up stale tunnels every 30 seconds (default)
If the CLI crashes or your network drops, your tunnel will be automatically cleaned up within ~60 seconds.

​
Quota Management

The server enforces a per-user tunnel quota (default: 5 active tunnels). Check your usage: 
rs-tunnel list
Free up quota: 
# Stop tunnels you're no longer using
rs-tunnel stop <tunnel-id-or-hostname>
Keep your tunnel list clean by stopping tunnels when you’re done with them, even though they’ll be cleaned up automatically if the CLI exits.

​
Working with Multiple Tunnels

You can run multiple tunnels simultaneously (up to your quota): 
# Terminal 1: Frontend
rs-tunnel up --port 3000 --url frontend

# Terminal 2: Backend API
rs-tunnel up --port 8080 --url backend

# Terminal 3: Database proxy
rs-tunnel up --port 5432 --url db-tunnel
Each tunnel:
  • Runs in its own CLI process
  • Has its own dashboard
  • Can be stopped independently

​
Self-Hosted Domain Override

All commands support the --domain flag for self-hosted deployments: 
rs-tunnel list --domain https://api.your-company.com
rs-tunnel stop <tunnel-id> --domain https://api.your-company.com
rs-tunnel logout --domain https://api.your-company.com
rs-tunnel doctor --domain https://api.your-company.com
The --domain flag is saved to ~/.rs-tunnel/config.json and applies to future commands. You only need to specify it once.

​
Examples

​
Daily Workflow

# Morning: Start your dev tunnels
rs-tunnel up --port 3000 --url my-app

# Check what's running
rs-tunnel list

# Evening: Clean up
rs-tunnel stop my-app.tunnel.example.com

​
Team Handoff

# Share your tunnel list with a teammate
rs-tunnel list

# They can access your tunnel at the hostname shown
# Stop when done
rs-tunnel stop <tunnel-id>

​
Troubleshooting

# Something not working?
rs-tunnel doctor

# Still having issues? Try logging out and back in
rs-tunnel logout
rs-tunnel login --email [email protected]

​
Next Steps

Configuration

Customize API domain and behavior

Troubleshooting

Solve common issues

Build docs developers (and LLMs) love

Get started for freeTalk to us