Install
On the Linux machine that will run your agents (a VPS or a home server; x86_64 or aarch64, with systemd):
curl -fsSL https://app.termenbox.dev/i | sh
Then open app.termenbox.dev on your phone or laptop, log in with GitHub, tap Add Server and scan the QR the command printed (or paste its link). That is the whole setup. The command carries no secret and is safe to run again.
[!TIP]
No camera? Paste the link the command printed into Add Server instead.
Pick your path
| You have | Run on the machine | Then |
|---|
| A VPS with a public IP | curl -fsSL https://app.termenbox.dev/i | sh | Scan the QR in Add Server. If it cannot connect, open the one UDP port the installer names. |
| A home server or laptop on your Wi-Fi | the same command | Scan the QR from a phone on the same Wi-Fi. No public IP, domain or router setting needed. |
| Workspaces isolated in Docker | curl -fsSL https://app.termenbox.dev/i | sh -s -- container | Scan the QR. Docker is installed if missing. |
| A dedicated user or root service | … | sh -s -- host-user or … | sh -s -- host | Scan the QR; asks for sudo. |
| Your own client and domain | the command your client shows | Follow BOOTSTRAP.md. |
| To remove it | curl -fsSL https://app.termenbox.dev/uninstall.sh | sudo sh | Shows what it would do first; add -s -- --yes to apply. |
[!IMPORTANT]
The default install runs workspaces directly on the machine as your own user, so the app gets a shell with your repositories, keys and agent logins. Choose the container path if that is more access than you want.
[!NOTE]
Windows: run it inside WSL2 with networkingMode=mirrored, otherwise other devices cannot reach it (details).
Connecting a home or WSL server
A server behind a router you cannot change, or inside WSL2's own NAT, cannot take an inbound UDP connection. Termenbox can still connect an assisted way, through a free Cloudflare account that you own. Nothing runs on the project's account, and nothing is shared with it.
On the server, once:
termenbox-server --setup-cloudflare # reads a Cloudflare API token from stdin, uses it once, never stores it
The token needs Workers Scripts: Edit, Account Settings: Read and Cloudflare Calls (create it at dash.cloudflare.com, My Profile, API Tokens). The command deploys a small signaling Worker (termenbox-relay-<hash>) and a TURN key in your account, keeps only the TURN key's id and its credential-minting token in relay.json (mode 0600, next to the server's other state), and prints the Worker's address, the free allowance and the cap.
- What the connection does. The phone and the server first try to punch a hole through both NATs with free public STUN (no account needed). If that does not connect within a few seconds, the session goes through your Cloudflare TURN relay. The session header says which: Punched or Relay.
- What it costs. Nothing on the free plan. Cloudflare's Realtime TURN includes 1,000 GB a month, shared with its other Realtime products, and charges $0.05 per GB beyond it. The server counts every relay credential it hands out as 128 MiB, and stops handing them out at a monthly cap of 500 GB (
TERMENBOX_RELAY_CAP_GB changes it), so a runaway cannot bill you.
- What it exposes. Only a client with a device certificate for you gets credentials, and each lasts 15 minutes. The Worker is a switchboard that holds no secret and checks nothing; the server verifies every message.
- Taking it away.
termenbox-server --teardown (token on stdin again) deletes the Worker, its Durable Object and the TURN key, and removes relay.json.
Not a LAN-only server: with TERMENBOX_LAN_ONLY the server never contacts STUN or the Worker. On WSL2 you can instead set networkingMode=mirrored (the installer prints the steps); --setup-cloudflare is the alternative when you cannot or would rather not.
Why Termenbox
- Built for the phone. Tabs per workspace, a key row for Esc, Ctrl and arrows, and a banner when an agent is waiting for you.
- Survives bad networks. The workspace runs in tmux on your server. Close the tab, lose signal or switch from Wi-Fi to cellular and it is still there; reconnecting re-attaches and repaints.
- Direct and private. The browser talks to your server over an encrypted WebRTC data channel on one UDP port. There is no relay in the middle, and our free directory only maps your server's key to its address.
- Works with your agents. Claude Code, Codex, OpenCode, or any program in a terminal. Notifications and agent status come from hooks you switch on yourself.
- Free and yours. MIT licensed. The hosted client and directory run on Cloudflare's free tier, and the server needs 512 MB of RAM and one vCPU.
Browser (app.termenbox.dev) ── WebRTC, direct, encrypted ──► Your machine
one UDP port termenbox-server + tmux
Questions
Yes. Install Termenbox on the machine where the agent runs, then use the app as the terminal: start the agent in a workspace, answer its questions from the banner, and come back later to the same workspace. Supported browsers: iOS Safari 16.4+, Chrome on Android 111+, current Chrome, Firefox, Edge and Safari on desktop.
The persistence is tmux's: the server keeps the workspace and each connection attaches to it. What Termenbox adds is a browser client made for touch, a connection that re-races its paths after a network change, and notifications. It is not an SSH client and does not need one.
No. It goes from your browser to your machine, encrypted, and the browser pins the server's fingerprint. Only a signed record (the server's public key and address) goes through the directory, and LAN addresses never do. Details: security and SECURITY.md.
On the same network as your phone, no: scan the QR and it connects over the LAN. On iPhone this depends on Safari's Local Network permission, which we have not finished testing; the link and QR work wherever the phone can reach the machine. Away from home you need one reachable UDP port, or an overlay such as Tailscale. A server behind carrier-grade NAT can only be reached from its own network or over an overlay until a relay exists. The app lists every path it tried and what to fix. See networking.
Nothing beyond the machine you run it on. There is no subscription, and using Termenbox never requires installing an app — the browser is the product.
Only the GitHub account that claims the server first, from a browser you have enrolled. Everyone else is refused.
Documentation
License
MIT
