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 whether the tunnel is running and, if so, its public URL.

band tunnel status

Example output when running:

running: yes
url: https://abc-def-123.trycloudflare.com

Example output when stopped:

running: no

Start the tunnel

Start a Cloudflare tunnel and print the public URL on stdout. 

band tunnel start
# https://abc-def-123.trycloudflare.com

The URL plus the auth token from ~/.band/settings.json is what you need 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 *.trycloudflare.com 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

Band requires a token for every authenticated request — local or remote. The token is generated on first launch (a 64-character hex string) and stored in ~/.band/settings.json under tokenSecret.

  • Read the token via jq -r .tokenSecret ~/.band/settings.json or by opening Settings → About in the dashboard.
  • Pass it to remote clients via the BAND_TOKEN environment variable, the ?token=… query string on first navigation (the server then sets a cookie), or the dashboard's mobile-friendly QR code.
  • The token is not rotated when the tunnel restarts; it persists in settings.json until you delete that field.

JSON output

band tunnel status --output json
band tunnel start  --output json
{
  "running": true,
  "url": "https://abc-def-123.trycloudflare.com"
}

Note that tunnel.status does not include the auth token — read it from ~/.band/settings.json as described above.