webpty

A multi-session web terminal that supervises long-running CLI agents (claude, codex, pwsh, …) per project folder. Open any browser on your trusted network — desktop or phone — and switch between live sessions with a swipe.

Built for the workflow: "My PC has claude --remote-control running in each of my project folders. I want to reach whichever one I need from my iPhone."

What it gives you

• Per-project supervisors — one PTY per registered folder, kept alive across browser disconnects.
• Auto-resume conversations — for claude, if a project already has a JSONL log in ~/.claude/projects/, webpty prepends -c on respawn so the chat continues instead of starting fresh.
• Mobile-first UI — full-screen-per-session, horizontal swipe to switch, kebab menu (Exit / Clear / Compact / other sessions / add).
• Quick PowerShell sessions — menu shortcut spawns a pwsh or elevated pwsh in the current session's CWD.
• Built on Microsoft's ConPTY via node-pty — same battle-tested PTY layer that VS Code uses.

Install

# global (recommended for `webpty` on PATH)
npm install -g @vitaldb/webpty

# or one-shot
npx -p @vitaldb/webpty webpty

Native dependency: node-pty (ships prebuilt binaries for Windows / macOS / Linux on Node 20+).

Run

webpty
# → [webpty] listening on http://0.0.0.0:4789
# → [webpty] config:    %APPDATA%\webpty\config.json   (Windows)
#                       ~/.config/webpty/config.json   (macOS / Linux)

Open http://<host>:4789/ from a browser on the same trusted network.

Configuration

config.json is generated on first launch under the data dir above.

{
  "bindHost": "0.0.0.0",
  "port": 4789,
  "tools": {
    "claude":           { "command": "claude",     "defaultArgs": "--remote-control" },
    "codex":            { "command": "codex",      "defaultArgs": "" },
    "powershell":       { "command": "powershell", "defaultArgs": "-NoLogo" },
    "powershell-admin": { "command": "gsudo",      "defaultArgs": "powershell -NoLogo" }
  },
  "sessions": []
}

Environment variables:

| Var | Purpose | |---|---| | WEBPTY_DATA_DIR | Override data/config directory. | | WEBPTY_PROJECTS_ROOT | Folder whose immediate subfolders show up in the Add Session dropdown. Defaults to the parent of the install dir. |

The previous PTYHUB_* and CSMWEB_* env vars are still honoured as fallbacks, and legacy %APPDATA%\ptyhub\ / %APPDATA%\CSMWeb\ data directories are auto-migrated on first launch.

Adding more tools

Add an entry to config.tools. The string in defaultArgs is shell-split and passed as argv.

PowerShell as Admin

The powershell-admin default uses gsudo to elevate inside the PTY. Install it once:

winget install gerardog.gsudo

Without gsudo, the admin shortcut fails with "File not found: gsudo" in the session's terminal. You can either install gsudo, replace the command in config.json, or run webpty itself elevated.

Security

webpty ships no authentication. It binds 0.0.0.0 so anyone who can reach the port can spawn shells / drive your claude session / read output. This is intentional: webpty is meant to live on a trusted network you've already locked down — for example:

• Tailscale — exposes the port only to your tailnet (this is the original author's setup). Use the device's tailnet IP / MagicDNS name from your phone.
• WireGuard / VPN to a private subnet.
• SSH local-forward to a remote host.
• bindHost: "127.0.0.1" if you only want loopback (then reverse-proxy in front of it).

If you need auth, put a reverse proxy with auth in front (Caddy / nginx with basic-auth or OAuth, Cloudflare Tunnel + Access, etc.).

Architecture

browser                              webpty server                          child
─────────                            ──────────────                          ─────
xterm.js  ───── WebSocket (binary) ──→  node-pty (ConPTY/forkpty)   ──→  claude / codex / pwsh
   ▲                                          │
   └─── /api/{config,projects,sessions} ──────┘

• src/server.js — Express + ws; serves the SPA, REST for session lifecycle, WebSocket per session id.
• src/session-manager.js — owns the node-pty children; handles spawn / resize / write / kill, plus claude auto-resume.
• src/config.js — JSON config persistence, legacy-dir migration on first run.
• public/ — single-page UI: per-session full-screen xterm pages in a swipe carousel; bottom dot indicator; kebab menu.

Differences from other web terminals

| | ttyd | gotty | wetty | webpty | |---|---|---|---|---| | Windows ConPTY | partial | no | via SSH | yes (node-pty) | | Multiple persistent sessions | no | no | no | yes | | Auto-resume agent conversations | n/a | n/a | n/a | yes (claude -c) | | Mobile-first swipe UX | no | no | no | yes | | Built-in auth | yes (token) | basic-auth | login | no — bring your own |

If you only need one generic shell in a browser, use ttyd. webpty's niche is many long-running LLM CLI sessions, one per project, reached from any device.

License

MIT