81585ad35f
- No hardcoded secrets; Origin+path+maxPayload checks verified wired in server.ts - No eval/exec; input is verbatim to PTY by design (byte-shuttle) - npm run build -> dist/server.js verified
77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
# Web Terminal
|
|
|
|
A browser-based terminal that exposes the **host machine's local shell** over WebSocket. Open `http://<host-ip>:3000` from any device on your LAN (phone, tablet, another computer) and you get a live, interactive terminal — primarily for **vibe coding**: hand Claude Code a task, walk away, reconnect from anywhere to check on it.
|
|
|
|
Sessions survive disconnects: the shell (and whatever's running in it) keeps going when you close the tab; reconnect and the output replays.
|
|
|
|
> ⚠️ **This hands a full shell to anyone who can reach the port.** LAN-only, no authentication. **Never** port-forward or tunnel it to the public internet. See [Security](#security).
|
|
|
|
## Requirements
|
|
|
|
- Node.js ≥ 18 (developed on v24)
|
|
- macOS/Linux. On macOS, `node-pty` compiles a native addon — install **Xcode Command Line Tools** (`xcode-select --install`) if `npm install` fails.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install # installs deps; postinstall makes node-pty's spawn-helper executable
|
|
```
|
|
|
|
## Run
|
|
|
|
```bash
|
|
npm run build:web # bundle the frontend (public/main.ts → public/build/main.js)
|
|
npm start # serve on 0.0.0.0:3000
|
|
```
|
|
|
|
Then:
|
|
|
|
```bash
|
|
# find your LAN IP (macOS):
|
|
ipconfig getifaddr en0
|
|
# open http://<that-ip>:3000 on any device on the same network
|
|
```
|
|
|
|
For frontend development, run `npm run dev:web` (esbuild --watch) alongside `npm start`.
|
|
|
|
## Configuration
|
|
|
|
All via environment variables (no hardcoding):
|
|
|
|
| Var | Default | Meaning |
|
|
|-----|---------|---------|
|
|
| `PORT` | `3000` | listen port |
|
|
| `BIND_HOST` | `0.0.0.0` | listen address |
|
|
| `SHELL_PATH` | `$SHELL` or `/bin/zsh` | shell to spawn |
|
|
| `IDLE_TTL` | `86400` (s) | reclaim a detached session after this idle time |
|
|
| `SCROLLBACK_BYTES` | `2097152` | per-session replay ring buffer (bytes) |
|
|
| `MAX_PAYLOAD_BYTES` | `1048576` | max single WS frame |
|
|
| `ALLOWED_ORIGINS` | (derived) | extra allowed WS origins, comma-separated |
|
|
|
|
`allowedOrigins` is **derived from the host's network-interface IPs** (plus `localhost` and anything in `ALLOWED_ORIGINS`) — never from `BIND_HOST`, since `0.0.0.0` is never a real browser Origin.
|
|
|
|
## Security
|
|
|
|
This is a no-auth, LAN-only tool by design. The defenses that matter:
|
|
|
|
- **Origin check (cannot be skipped):** the WS handshake rejects any `Origin` not on the allow-list (HTTP 401). This blocks Cross-Site WebSocket Hijacking — a malicious page in your browser trying to connect to `ws://<your-lan-ip>:3000`.
|
|
- **Path-scoped upgrades:** only `/term` is accepted for WS upgrade.
|
|
- **Frame size cap:** oversized frames are rejected (`MAX_PAYLOAD_BYTES`).
|
|
- **Never expose to the public internet.** `ws://` is **unencrypted** — on an untrusted network (café/office Wi-Fi) traffic (including keystrokes: passwords, API keys) can be sniffed. The recommended deployment is **[Tailscale](https://tailscale.com/)** (WireGuard-encrypted), which also lets you use `wss://` (the frontend auto-selects `wss` on HTTPS).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm test # vitest, all modules
|
|
npm run typecheck # tsc (backend + frontend)
|
|
npm run build # compile backend to dist/
|
|
```
|
|
|
|
Real-PTY end-to-end tests (`test/integration/`) auto-skip where `posix_spawn` is unavailable (e.g. sandboxes) and run everywhere else.
|
|
|
|
## How it works
|
|
|
|
The server is a **byte-shuttle, not a terminal**: `node-pty` provides a pseudo-terminal so the shell believes it has a real TTY, and `xterm.js` in the browser interprets the ANSI bytes and renders. The server never parses terminal semantics. PTY lifecycle is decoupled from the WebSocket — a disconnect *detaches* (the PTY keeps running) rather than killing it, which is what makes session survival work.
|
|
|
|
Design and rationale: [`docs/TECH_DOC.md`](docs/TECH_DOC.md) (why) and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) (how).
|