WebTerminal runs a real interactive bash session inside the browser. The server opens a PTY on the host, loads the usual bash profile files when they exist, and presents a modern xterm.js surface over a WebSocket link so keystrokes and output stay in sync.
The product’s distinctive behaviour is identity masking for the interactive prompt: configurable fake username and hostname values appear in PS1 and in related shell variables so screenshots and recorded demos can avoid advertising the real account name on the machine. Masking is cosmetic for the prompt path; it is not a sandbox and it does not rewrite every command result.
Official project page · Security · Contributing
WebTerminal 1.1 — closed maquette. This maquette is finished and stable for its intended local use. There is no schedule of regular updates and no automated test or regression suite. Obvious bugs may still be fixed case by case. Further product context lives on the official project page.
This single high-definition capture is the visual reference for the maquette. The shell sits in a translucent panel on the left so a stylized black panther remains visible on the right without covering the text. Glyphs are oversized on purpose so a human can read the prompt at a glance. The cut is paced slowly so typed commands stay readable.
The opening beat shows the demo box identity with whoami / hostname resolving to demo and web-terminal. The middle beat cycles masked prompts — clac@neonforge, jack@blingterm, marie@pixelbash, sophie@mintstage, lea@neonforge — then prints Midnight Commander package metadata from the local apt cache. The closing beat repeats whoami / hostname under the last masked prompt to underline the contrast, then opens the official project sheet at dreamproject.online/prj/webterminal/.
Clone the repository, install Node dependencies, and copy the environment template before the first run.
git clone https://github.com/JeanSebastienBash/WebTerminal.git
cd WebTerminal
npm install
cp .env.example .envEdit .env when the default port or masked identity should change.
PORT=3000
FAKE_USERNAME=dev
FAKE_HOSTNAME=workstationStart the server with npm start for a normal run or npm run dev while iterating with nodemon. Open http://127.0.0.1:3000/ in a local browser. Stop the process with Ctrl+C in the terminal that launched it.
Requirements are Node.js 18 or newer, a Unix-like host where node-pty can spawn bash, and bash itself available on the PATH.
The browser loads the static UI from public/. A WebSocket to the same origin carries input, output, and resize messages. For each connection the Node process spawns bash -i through node-pty, inherits most of the host environment, points the session at the real home directory, and overrides USER and LOGNAME with the configured fake username.
Shortly after spawn, the server sources ~/.bashrc, ~/.bash_profile, and ~/.bash_aliases when those files exist, exports the fake identity into the shell, forces a coloured PS1 that embeds the fake username and hostname, and clears the screen so the first visible prompt already shows the mask.
The runtime is plain Node.js. Express serves the static front end. The ws library attaches the WebSocket server to the same HTTP listener. node-pty owns the interactive bash process. dotenv loads .env for PORT, FAKE_USERNAME, and FAKE_HOSTNAME. The browser side is xterm.js with the Fit and Web Links addons, vendored under public/lib/ so the UI works without a separate front-end build step.
Almost all server behaviour lives in src/server.js: static middleware, WebSocket connection handling, PTY lifecycle, resize, and the delayed profile-plus-prompt injection. The page shell and client wiring live in public/index.html.
WebTerminal executes real commands on the host that runs the Node server. Treat it as a local or trusted-network convenience for screenshots and video segments that need a terminal in frame, not as a hardened remote access service.
There is no authentication on the HTTP or WebSocket endpoints. The default listen behaviour accepts connections on the configured port without binding exclusively to loopback, so exposing the port on an untrusted network hands callers a live shell as the server user.
Identity masking changes the interactive prompt and selected environment variables. It does not reliably change the results of whoami, id, the system hostname command, home paths expanded by \w or pwd, inherited environment values, or error text that embeds real filesystem locations. Operators must choose safe commands and re-read outputs before publishing any image or recording.
Bash profiles sourced at connect time can redraw the prompt, print banners, or otherwise undo the cosmetic mask. The working directory begins in the real home directory unless the operator moves elsewhere. There is no automated test suite in this repository; correctness for a given machine is verified by following the install steps and checking the UI manually.
Use the tool sparingly and only when a real shell with a masked prompt is actually required for media production. Prefer 127.0.0.1 access, keep .env out of version control, and shut the server down when the capture session ends.
MIT License — see LICENSE.
Publisher: DreamProjectAI · Project sheet: webterminal