Getting Started

Install the prerequisites

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

# Check if installed
node --version

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# macOS
brew install cloudflared

# Linux - see cloudflare.com/downloads

Run Termbridge

npx termbridge

You'll see output like this:

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

Connect from your phone

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

That's it - you're connected!

What just happened?

1. Termbridge started a local server on your machine
2. It created a tmux session for your terminal
3. Cloudflare created a secure tunnel (the trycloudflare.com URL)
4. The QR code contains a one-time token for secure access
5. When you scanned it, you got a session cookie and connected

Try it out

Once connected, try some commands:

# 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 in dev 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.

Next steps