TermBeam Mobile

Beam your terminal to any device. Forked from TermBeam.

TermBeam lets you access your terminal from a phone, tablet, or any browser — no SSH, no port forwarding, no configuration needed. Run one command and scan the QR code.

Repository

https://github.com/user-attachments/assets/9dd4f3d7-f017-4314-9b3a-f6a5688e3671

Mobile UI

Quick Start

npx termbeam-mobile

Or install globally:

npm install -g termbeam-mobile
termbeam-mobile

Scan the QR code printed in your terminal, or open the URL on any device.

If you plan to reuse the same endpoint often, run with --persisted-tunnel and a fixed --password so the URL and login stay stable across restarts.

For this project, DevTunnels is a better fit than ngrok because its free-tier usage limits are usually looser for monthly traffic and request volume.

termbeam-mobile                        # tunnel + auto-password (default)
termbeam-mobile --password mysecret    # custom password
termbeam-mobile --no-tunnel            # LAN only
termbeam-mobile -i                     # interactive setup wizard

Features

Mobile-First

• No SSH client needed — just open a browser on any device
• Touch-optimized key bar with arrows, Tab, Ctrl, Esc, copy, paste, and more
• Swipe scrolling, pinch zoom, and text selection overlay for copy-paste
• iPhone PWA safe-area support for a native-app feel

Multi-Session

• Tabbed terminals with drag-to-reorder and live tab previews on hover/long-press
• Split view — two sessions side-by-side (auto-rotates horizontal/vertical)
• Session colors and activity indicators for at-a-glance status
• Folder browser for picking working directory, optional initial command per session

Productivity

• Terminal search with regex, match count, and prev/next navigation
• Command palette (Ctrl+K / Cmd+K) for quick access to all actions
• File upload — send files from your phone to the session's working directory
• File browser & download — browse files in a session's working directory from the side panel and download them to your device
• Markdown viewer — preview .md files rendered with GitHub Flavored Markdown directly in the browser
• Git changes view — view git status, diffs, blame, and commit history in the code viewer. Toggle between Files and Changes tabs, view staged/unstaged diffs with syntax highlighting, and see per-line blame annotations
• Push notifications — get native push notifications on your phone when commands complete, even when the app is in the background. Uses Web Push API with VAPID authentication
• In-app updates — auto-update from the UI for npm/yarn/pnpm global installs, with copy-command fallback for other methods
• Completion notifications — browser alerts when background commands finish
• 30 color themes with adjustable font size
• Port preview — reverse-proxy a local web server through TermBeam
• Image paste from clipboard

Secure by Default

• Auto-generated password with rate limiting and httpOnly cookies
• QR code auto-login with single-use share tokens (5-min expiry)
• DevTunnel integration for secure remote access — ephemeral or persisted URLs
• Security headers (X-Frame-Options, CSP, nosniff) on all responses; only detected shells allowed

How It Works

TermBeam starts a lightweight web server that spawns a PTY (pseudo-terminal) with your shell, serves a mobile-optimized xterm.js UI via Express, and bridges the two over WebSocket. Multiple clients can view the same session simultaneously, and sessions persist when all clients disconnect.

flowchart LR
  A["Phone / Browser"] <-->|WebSocket| B["TermBeam Server"]
  B <-->|PTY| C["Shell (zsh/bash)"]
  B -->|Express| D["Web UI (xterm.js)"]
  B -.->|Optional| E["DevTunnel"]

CLI Highlights

| Flag | Description | Default | | --------------------- | ----------------------------------------------- | -------------- | | --password <pw> | Set access password | Auto-generated | | --no-password | Disable password protection | — | | --tunnel | Create an ephemeral devtunnel URL | On | | --no-tunnel | Disable tunnel (LAN-only) | — | | --persisted-tunnel | Reusable devtunnel URL (stable across restarts) | Off | | --port <port> | Server port | 3456 | | --host <addr> | Bind address | 127.0.0.1 | | --lan | Bind to all interfaces (LAN access) | Off | | --public | Allow public tunnel access (no Microsoft login) | Off | | -i, --interactive | Interactive setup wizard | Off | | --log-level <level> | Log verbosity (error/warn/info/debug) | info |

For all flags, subcommands, and environment variables, see the Configuration docs.

Security

TermBeam auto-generates a password and creates a secure tunnel by default, binding to 127.0.0.1 (localhost only). Auth uses httpOnly cookies with 24-hour expiry, login is rate-limited to 5 attempts per minute, QR codes contain single-use share tokens (5-min expiry), and security headers (X-Frame-Options, CSP, nosniff) are set on all responses.

For repeatable local workflows, --persisted-tunnel plus a fixed password is the least annoying setup: you keep the same public URL and do not have to re-share access details every restart.

For the full threat model and safety checklist, see SECURITY.md. For detailed security documentation, see the Security Guide.

Contributing

Contributions welcome — see CONTRIBUTING.md.

Changelog

See CHANGELOG.md for version history.

License

MIT

Acknowledgments

Special thanks to @tamirdresher for the blog post that inspired the solution idea for this project, and for his cli-tunnel implementation.