Getting Started

View as Markdown Edit on GitHub Docs at 1675df8

Install the prerequisites

For the default local tunnel setup, install these tools on your computer:

Node.js 20+

Download from nodejs.org or use your package manager.

Shell

# Check if installed
node --version

tmux

The terminal multiplexer that powers Termbridge sessions.

Shell

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

cloudflared

Creates the secure tunnel to your terminal (not needed for sandbox direct mode).

Shell

# macOS
brew install cloudflared

# Linux - see cloudflare.com/downloads

Download cloudflared

Run Termbridge

Shell

npx termbridge

You'll see output like this:

Code

┌─────────────────────────────────────────┐
│  Termbridge                             │
│                                         │
│  Local:   http://127.0.0.1:51234        │
│  Public:  https://abc123.trycloudflare.com │
│                                         │
│  ██████████████                         │
│  ██          ██  <- Scan this QR code   │
│  ██████████████                         │
│                                         │
└─────────────────────────────────────────┘

Note The trycloudflare.com URL is a quick, account-less tunnel. If you use Termbridge frequently, set up a named Cloudflare tunnel token to avoid rate limits.

Connect from your phone

Open your phone's camera
Point it at the QR code
Tap the link that appears
Your terminal loads in the browser

That's it - you're connected!

What just happened?

Termbridge started a local server on your machine
It created a tmux session for your terminal
Cloudflare created a secure tunnel (the trycloudflare.com URL)
The QR code contains a one-time token for secure access. It works once and expires 90 seconds after startup, so scan it promptly; if it has expired, restart Termbridge for a new one
When you scanned it, you got a session cookie and connected

Try it out

Once connected, try some commands:

Shell

# See system info
htop

# Check a git repo
cd ~/your-project && git status

# Run any CLI tool

The terminal supports full colors, TUIs, and all the keys you'd expect.

Keep it running

Termbridge needs to stay running for the connection to work. When you're done:

Press Ctrl+C in the terminal where Termbridge is running
The tunnel closes and the connection ends
Your tmux session stays alive (unless you used --kill-on-exit)

First session behavior

Termbridge creates a tmux session (default name is derived from the port)
The first terminal in the list is loaded automatically
You can create multiple sessions on startup by setting TERMBRIDGE_SESSIONS=2

Using an existing tmux session

If you pass --session <name> and that session already exists, Termbridge will attach to it instead of creating a new one. This is useful for monitoring long-running processes you've already started.