TermBeam Configuration

CLI Flags

Flag	Description	Default
`--password <pw>`	Set access password (also accepts `--password=<pw>`)	Auto-generated
`--generate-password`	Auto-generate a secure password (default behavior)	On
`--no-password`	Disable password authentication (cannot combine with `--public`)	—
`--tunnel`	Create an ephemeral devtunnel URL (private access)	On
`--no-tunnel`	Disable tunnel	—
`--persisted-tunnel`	Create a reusable devtunnel URL (stable across restarts)	Off
`--public`	Allow public tunnel access (no Microsoft login required)	Off
`--port <port>`	Server port (must be 1-65535)	`3456`
`--host <addr>`	Bind address	`127.0.0.1`
`--lan`	Bind to all interfaces (LAN access)	Off
`-i, --interactive`	Interactive setup wizard — walks through password, port, access mode (tunnel type, visibility), and log level	Off
`--force`	Stop any existing TermBeam server before starting a new one	Off
`-h, --help`	Show help	—
`-v, --version`	Show version	—
`--log-level <level>`	Set log verbosity: `error`, `warn`, `info`, `debug`	`info`

Environment Variables

Variable	Description	Default
`PORT`	Server port	`3456`
`TERMBEAM_PASSWORD`	Access password	None
`TERMBEAM_CWD`	Default working directory	Current directory
`TERMBEAM_LOG_LEVEL`	Log level	`info`
`TERMBEAM_CONFIG_DIR`	Location for `connection.json` and other config files	`~/.termbeam/`
`SHELL`	Fallback shell on Unix (used only if auto-detection fails)	`/bin/sh`
`COMSPEC`	Fallback shell on Windows (used only if auto-detection fails)	`cmd.exe`

Settings (UI)

TermBeam exposes settings through the Tools panel, opened from the floating ▦ button or Ctrl/Cmd+K. From there pick Settings… (or use the Cmd/Ctrl+, shortcut). On mobile the panel slides up from the bottom; on desktop it docks to the right (~420 px wide). It is non-blocking so theme, font size, collapsed-touchbar and haptics changes can be observed live against the terminal underneath.

For the full UI walkthrough — Tools panel sections, Settings panels, Touch Bar key editor, Workspaces — see Customization.

Where preferences are stored

Preferences are persisted server-side in ~/.termbeam/prefs.json (mode 0o600) via the authenticated GET /api/preferences and PUT /api/preferences endpoints. The browser keeps a localStorage cache (termbeam-prefs) for instant first paint and offline UX, but the server file is the source of truth — opening TermBeam from a phone, tablet and laptop against the same instance gets the same settings.

The schema is roughly:

{
  "themeId": "one-dark",
  "fontSize": 13,
  "notifications": false,
  "haptics": true,
  "defaultFolder": "",
  "defaultInitialCommand": "",
  "touchBarCollapsed": true,
  "touchBarKeys": [{ "id": "esc", "label": "Esc", "send": "\u001b", "row": 1, "col": 1 }],
  "workspaces": [
    {
      "name": "DevWorkspace",
      "default": true,
      "sessions": [
        {
          "name": "server",
          "cwd": "/path",
          "shell": "/bin/zsh",
          "color": "#4a9eff",
          "initialCommand": "npm run dev",
        },
      ],
    },
  ],
  "startupWorkspace": { "enabled": false, "sessions": [] }, // legacy
}

The legacy device-local keys below are still read once on first load after upgrade and migrated into the unified store; they remain device-only:

Key	Description
`termbeam-tab-order`	Saved tab order (JSON array of session IDs).
`termbeam-hub-filter`	Last-used filter on the SessionsHub page.
`termbeam-push-subscribed`	Whether the browser is subscribed to push notifications.
`termbeam-review-comments:*`	Per-PR review-comment state (Copilot integration).

These can be cleared at any time via the browser’s developer tools.

Subcommands

`termbeam service`

TermBeam includes a service subcommand for managing a PM2-based background service. Run termbeam service install to launch an interactive wizard that configures and starts the service.

Subcommand	Description
`service install`	Interactive wizard — configures password, port, access mode, and more
`service uninstall`	Stops the PM2 process, removes it, and deletes the ecosystem config
`service status`	Shows detailed PM2 process status (uptime, memory, restarts)
`service logs`	Tails PM2 logs (last 200 lines + live stream)
`service restart`	Restarts the PM2 process

For a full walkthrough of the wizard steps and each subcommand, see Running in Background.

Examples

Basic Usage

# Start with defaults (tunnel + auto-generated password)
termbeam

# Start without tunnel (LAN only, auto-generated password)
termbeam --no-tunnel

# Start without password (not recommended)
termbeam --no-password

# Use a specific shell
termbeam /bin/bash

# Use fish shell with custom port
termbeam --port 8080 /usr/bin/fish

Interactive Setup

# Launch the guided setup wizard
termbeam -i

The wizard walks through password, port, access mode, and log level with an interactive TUI.

With Authentication

# Set an explicit password
termbeam --password mysecret

# Use environment variable
TERMBEAM_PASSWORD=mysecret termbeam

Network Access

By default, TermBeam binds to localhost only. Use --lan or --host 0.0.0.0 to allow connections from other devices on your network.

# Localhost only (default behavior)
termbeam

# Allow LAN access
termbeam --lan

# Allow LAN access (equivalent to --lan)
termbeam --host 0.0.0.0

# Tunnel is on by default (private, owner-only access)
termbeam

DevTunnel

The --tunnel flag creates a private URL using Azure DevTunnels. By default, only the tunnel owner (you) can access it — visitors must authenticate with the same Microsoft account used by devtunnel user login:

termbeam --password mysecret

To allow public access (anyone with the URL can connect), add --public:

termbeam --public --password mysecret

For a stable URL that persists across restarts, use --persisted-tunnel:

termbeam --persisted-tunnel --password mysecret

Requirements:

devtunnel CLI — TermBeam will offer to install it automatically if not found
Login is handled automatically — if not already logged in, TermBeam will attempt browser login first, then fall back to device code flow if the browser is unavailable (useful in WSL or headless environments)