WebShell

Shared web console for Codex, Claude, and shell sessions, built with xterm.js.

Screenshots

Dashboard Overview	Shared Terminal Grid
Launch, monitor, and switch between multiple persistent Codex, Claude, and shell sessions.	Keep synchronized terminal viewers open side by side across different browser windows and devices.
Mobile Layout
Compact mobile view with the same shared session workflow, optimized for smaller screens.

What it does

• Uses @xterm/xterm plus the requested addons: attach, clipboard, fit, image, ligatures, progress, search, serialize, unicode-graphemes, unicode11, web-links, webgl.
• Keeps PTY processes alive on the server when a browser tab closes.
• Lets multiple devices attach to the same session simultaneously.
• Auto-grows shared PTY geometry for larger viewers and scales smaller viewers down in the browser.
• Supports multiple concurrent monitored sessions in one dashboard.
• Uses One Half Dark colors and prefers BlexMono Nerd Font with Microsoft YaHei UI fallback.

Run

npm install
npm run dev

Development:

• Frontend: http://<host>:5173
• Backend: http://<host>:3000

Production:

npm run build
npm start

Production serves the built client from the backend on port 3000.

Package as EXE

Windows packaging is provided through Node SEA.

npm run package:exe

Output:

• dist-exe/windows-x64/WebShell.exe
• dist-exe/windows-x64/webshell.config.json

The packaged executable extracts its runtime files to .webshell-runtime next to the exe on first launch. You can keep editing webshell.config.json beside the exe to change preset names and default command lines.

Preset config

Preset names and command lines are loaded from webshell.config.json by default.

Example:

{
  "presets": {
    "codex": {
      "name": "Codex",
      "commandLine": "codex"
    },
    "claude": {
      "name": "Claude",
      "commandLine": "claude"
    },
    "shell": {
      "name": "Shell",
      "commandLine": ""
    },
    "custom": {
      "name": "Custom",
      "commandLine": ""
    }
  }
}

• name controls the preset name shown in the UI.
• commandLine controls the default launch command for that preset.
• description is optional. If omitted, the built-in description is kept.
• Set WEBSHELL_CONFIG to load a different config file path.

Session lifecycle

• Closing a web page detaches the viewer only. It does not terminate Codex, Claude, or the shell session.
• Terminals stop only when you explicitly press Terminate or call the terminate API.
• Exited sessions can be removed from the control plane with Remove.

Geometry model

• Each session has one canonical PTY size on the server.
• When a larger viewer connects, the session can auto-grow.
• Smaller viewers render the same session through client-side scaling.
• If you want to explicitly shrink the PTY to the current viewport, use Use Viewport Size.

This avoids disconnect-driven reflow while still keeping different device sizes usable.

Fonts

Install BlexMono Nerd Font on client devices for the intended terminal look. If it is not available, the UI falls back gracefully to Microsoft YaHei UI, Microsoft YaHei, Cascadia Mono, SFMono-Regular, Consolas, and monospace.

Useful environment variables

• WORKSPACE_ROOT: default working directory for new sessions.
• WEBSHELL_SHELL: override the server shell executable.
• WEBSHELL_CONFIG: override the preset config file path.
• WEBSHELL_CLIENT_DIST: override the built frontend directory.

API

• GET /api/presets
• GET /api/sessions
• GET /api/sessions/:sessionId
• POST /api/sessions
• POST /api/sessions/:sessionId/viewers/:viewerId/size
• POST /api/sessions/:sessionId/geometry
• POST /api/sessions/:sessionId/terminate
• DELETE /api/sessions/:sessionId