CLI Reference

View as Markdown Edit on GitHub Docs at 1675df8

Basic usage

Just run the command - no arguments needed:

Shell

npx termbridge

This starts everything: local server, tmux session, and the default Cloudflare tunnel.

Running termbridge without a subcommand is equivalent to termbridge start.

You can also run termbridge start explicitly with all flags:

Shell

termbridge start --port 8080 --proxy 5173 --session dev --kill-on-exit --no-qr --tunnel cloudflare

Flags

Flag	What it does	Default
`--port <port>`	Use a specific port instead of a random one	Random
`--proxy <port>`	Proxy a local dev server (enables Terminal/Preview views)	-
`--session <name>`	Name your tmux session	Auto-generated
`--kill-on-exit`	Clean up tmux sessions when Termbridge exits	Off
`--no-qr`	Don't print the QR code (useful for scripts)	Off
`--no-tunnel`	Disable the tunnel (requires `--public-url`)	Off
`--public-url <url>`	Public URL when tunnel is disabled	-
`--tunnel <provider>`	Tunnel provider (`cloudflare` or `none`)	cloudflare
`--tunnel-token <token>`	Use a named Cloudflare Tunnel token (requires `--port`)	-
`--tunnel-url <url>`	Public URL for the named tunnel (required with `--tunnel-token`)	-
`--backend <backend>`	Terminal backend (`tmux` or `sandbox-daytona`)	tmux
`--sandbox-repo <url>`	Repo URL to clone into the Daytona sandbox	-
`--sandbox-branch <branch>`	Branch to check out in the sandbox	-
`--sandbox-path <path>`	Repo path in the sandbox	Derived from the repo name
`--sandbox-name <name>`	Sandbox name	Random `termbridge-<hex>`
`--sandbox-preview-port <port>`	Preview port in the sandbox	-
`--sandbox-public`	Create a public sandbox	Off (on in direct mode)
`--sandbox-direct`	Run the server inside the Daytona sandbox (no tunnel)	Off
`--dev-proxy-url <url>`	Proxy preview traffic to this URL instead of `localhost:<proxy port>` (used by the dev scripts)	-
`-h`, `--help`	Print the help text	-

Any other option fails with unknown option: <flag>. There is no --version flag.

A flag wins over its environment variable, with one exception: TERMBRIDGE_TUNNEL currently overrides --tunnel and --no-tunnel (#5).

Note The built-in termbridge --help output still lists --daytona-* flags and --backend tmux | daytona. Those names are rejected; use the --sandbox-* flags and --backend sandbox-daytona from the table above (#1).

Examples

Attach to an existing tmux session

If you already have a tmux session running:

Shell

termbridge --session my-session

Fixed port and custom session

Shell

termbridge --port 8080 --session codex

Clean exit (no leftover sessions)

Shell

termbridge --kill-on-exit

Scripting (no QR output)

Shell

termbridge --no-qr

Proxy a Vite dev server

Shell

# Start your Vite app first
cd my-app && npm run dev  # runs on port 5173

# Then start Termbridge with proxy
termbridge --proxy 5173

Use the Views button to switch between Terminal and Preview. Preview loads your app through the proxy with HMR support.

Named Cloudflare tunnel (token-based)

If you have a Cloudflare account and want to avoid trycloudflare rate limits:

Shell

termbridge --port 8080 --tunnel-token <TOKEN> --tunnel-url https://term.example.com

Disable the tunnel (bring your own public URL)

Shell

termbridge --no-tunnel --public-url https://example.com

Environment variables

Termbridge reads environment variables from the shell and from a .env file in the directory you run it from. Variables already set in the shell take precedence over the .env file.

Core settings

Variable	What it does
`TERMBRIDGE_SESSIONS=2`	Create multiple tmux sessions on startup
`TERMBRIDGE_TMUX_CWD=/path`	Working directory for new tmux sessions
`TERMBRIDGE_PUBLIC_URL=https://example.com`	Public URL when tunnel is disabled
`TERMBRIDGE_TUNNEL=none`	Disable the tunnel
`TERMBRIDGE_TUNNEL_TOKEN=<token>`	Named tunnel token (requires `TERMBRIDGE_TUNNEL_URL`)
`TERMBRIDGE_TUNNEL_URL=https://term.example.com`	Public URL for the named tunnel

Advanced

Daytona direct mode sets these for the server it runs inside the sandbox. You can also set them yourself.

Variable	What it does
`TERMBRIDGE_HOST=0.0.0.0`	Address the server binds to (default `127.0.0.1`). The printed local URL always shows `127.0.0.1`.
`TERMBRIDGE_COOKIE_SAMESITE=lax`	`SameSite` value of the session cookie: `lax`, `strict` or `none` (default `Lax`, or `None` in direct mode)
`TERMBRIDGE_SHARE_FILE=/path/share-url.txt`	Also write the share URL to this file
`TERMBRIDGE_HIDE_TERMINAL_SWITCHER=1`	Hide the terminal switcher in the UI
`TERMBRIDGE_TMUX_PATH_PREFIX=/path/bin`	Prepend this to `PATH` in each tmux session Termbridge starts or attaches to (typed into the session as an `export` command)

Development

Variable	What it does
`TERMBRIDGE_INSECURE_COOKIE=1`	Allow HTTP cookies (local dev only)
`TERMBRIDGE_PROXY_PORT=5173`	Proxy port for dev:beam:proxy script
`TERMBRIDGE_DEV_UI=http://127.0.0.1:5000`	Override Vite dev UI URL
`TERMBRIDGE_DEV_PORT=3000`	Override Termbridge server port in dev (default `8787`)
`TERMBRIDGE_DEV_SESSION=codex`	tmux session name for `dev:beam` (default `codex`)
`TERMBRIDGE_SKIP_BUILD=1`	Skip the CLI build in `dev:beam`

Sandbox (Daytona)

Variable	What it does
`TERMBRIDGE_BACKEND=sandbox-daytona`	Use the Daytona sandbox backend
`TERMBRIDGE_SANDBOX_DIRECT=true`	Run Termbridge inside the sandbox
`TERMBRIDGE_SANDBOX_SERVER_PORT=8080`	Port for the sandboxed server
`TERMBRIDGE_SANDBOX_AGENTS=claude-code,codex`	Auto-install + sync auth for agents
`TERMBRIDGE_SANDBOX_AGENT_ENV=...`	Extra env vars to forward
`TERMBRIDGE_SANDBOX_AGENT_AUTH_PATHS=...`	Local auth files to sync

For full Daytona configuration, see the Daytona guide.

Stopping Termbridge

Press Ctrl+C in the terminal where Termbridge is running. This:

Closes the tunnel (if enabled)
Stops the local server
Keeps tmux sessions alive (unless you used --kill-on-exit)

Your tmux sessions persist by default, so you can reconnect later.