# Getting Started

## Install the prerequisites

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

### Node.js 20+

Download from [nodejs.org](https://nodejs.org) or use your package manager.

```bash
# Check if installed
node --version
```

### tmux

The terminal multiplexer that powers Termbridge sessions.

```bash
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux
```

### cloudflared

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

```bash
# macOS
brew install cloudflared

# Linux - see cloudflare.com/downloads
```

[Download cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)


## Run Termbridge

```bash
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   │
│  ██████████████                         │
│                                         │
└─────────────────────────────────────────┘
```

> **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

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. It works once and expires 90 seconds after startup, so scan it promptly; if it has expired, restart Termbridge for a new one
5. When you scanned it, you got a session cookie and connected

## Try it out

Once connected, try some commands:

```bash
# 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.

## Next steps

### [Mobile Controls](/docs/usage/mobile-controls)

Tips for using Termbridge on phones and tablets

### [Multiple Terminals](/docs/usage/multiple-terminals)

Run several sessions and switch between them

### [Dev Server Preview](/docs/usage/dev-server-preview)

Preview your Vite app alongside the terminal

### [CLI Reference](/docs/cli)

See all available flags and options