Band Band

band tunnel

The band tunnel command group manages the Cloudflare tunnel that enables remote access to your Band server. When the tunnel is running, you can access the dashboard and API from any device over the internet — including your phone.

Prerequisites

The tunnel feature requires cloudflared to be installed on your system. Cloudflared is Cloudflare's open-source tunnel client. 

# macOS
brew install cloudflared

# Linux
sudo apt install cloudflared

# Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

You do not need a Cloudflare account. Band uses cloudflared's quick tunnel feature, which generates a temporary public URL without any configuration.

Check Tunnel Status

Display the current tunnel state, URL, and connection info.

band tunnel status

Example output when running:

Status:    running
URL:       https://abc-def-123.trycloudflare.com
Uptime:    2h 34m
Subdomain: abc-def-123

Example output when stopped:

Status:    stopped

Start the Tunnel

Start a Cloudflare tunnel to make your local Band server accessible from the internet. 

band tunnel start

Once started, Band generates an authentication token and prints the public URL. You can share this URL along with the token to access Band from another device.

Stop the Tunnel

Shut down the tunnel and revoke the public URL.

band tunnel stop

Custom Subdomains

By default, cloudflared assigns a random subdomain. If you have a Cloudflare account and a configured domain, you can set up a persistent subdomain through Cloudflare's dashboard. This gives you a stable URL like https://band.yourdomain.com.

Security

When the tunnel is active, Band generates a random authentication token. Remote clients must include this token (via the BAND_TOKEN environment variable or the login screen in the web interface) to access the API.

  • The token is displayed when the tunnel starts.
  • The token is also available via band tunnel status --output json.
  • Tokens are rotated each time the tunnel is restarted.
  • The dashboard shows a QR code for easy mobile access with the token embedded.

JSON Output

band tunnel status --output json
{'{'}
  "status": "running",
  "url": "https://abc-def-123.trycloudflare.com",
  "token": "bnd_a1b2c3d4e5f6...",
  "uptimeSeconds": 9240
{'}'}