Node PTY Demo

A small TypeScript demo for running a real shell through node-pty. It includes both a local terminal bridge and a browser-based terminal UI powered by xterm.js over WebSockets.

Features

• Spawns the default system shell with node-pty
• Runs directly in the current terminal with raw input forwarding
• Serves an xterm.js browser terminal at http://127.0.0.1:3000
• Handles terminal resize messages from the browser client
• Supports optional token protection for the browser terminal WebSocket
• Requires a token when binding to a non-loopback host

Prerequisites

• Node.js
• pnpm

Installation

pnpm install

Usage

Local PTY

Start a shell inside the current terminal:

pnpm dev

By default, the app uses your platform shell:

• Windows: pwsh.exe
• macOS: $SHELL or zsh
• Linux: $SHELL or bash

You can also pass a shell and arguments:

pnpm dev /bin/bash --login

Browser Terminal

Start the HTTP and WebSocket server:

pnpm dev:web

Open:

http://127.0.0.1:3000

The page in public/index.html connects to the /terminal WebSocket endpoint and streams input/output to a node-pty shell.

Configuration

The server loads environment variables from .env automatically. Use .env.example as a starting point:

HOST=127.0.0.1
PORT=3000
# TERMINAL_TOKEN=change-me

HOST defaults to 127.0.0.1 and PORT defaults to 3000.

TERMINAL_TOKEN is optional for local loopback use. If set, open the browser with the same token:

TERMINAL_TOKEN=change-me
pnpm dev:web

http://127.0.0.1:3000/?token=change-me

If you bind HOST to a non-loopback address such as 0.0.0.0, TERMINAL_TOKEN is required because the server exposes a real PTY shell.

Scripts

• pnpm dev: run the local PTY terminal
• pnpm dev:web: run the browser terminal server
• pnpm build: compile TypeScript to dist/
• pnpm prod: run the compiled local PTY terminal
• pnpm prod:web: run the compiled browser terminal server

Build

pnpm build

Run the compiled apps:

pnpm prod
pnpm prod:web

macOS pnpm Note for node-pty

If you see this error on macOS when opening the browser terminal:

Error: posix_spawnp failed.

The node-pty macOS spawn-helper binary may not have executable permission after installation with pnpm.

Check the permission:

ls -l node_modules/.pnpm/node-pty@*/node_modules/node-pty/prebuilds/darwin-*/spawn-helper

If the output shows permissions like this:

-rw-r--r--

fix it with:

chmod +x node_modules/.pnpm/node-pty@*/node_modules/node-pty/prebuilds/darwin-*/spawn-helper

Then start the browser terminal again:

pnpm dev:web

Project Structure

• src/index.ts: local terminal entry point
• src/server.ts: HTTP and WebSocket server for the browser terminal
• src/terminal.ts: shared node-pty shell helpers
• public/index.html: xterm.js browser terminal UI
• .env.example: server configuration example
• dist/: compiled JavaScript output

Security

This project exposes an interactive shell. Keep the server bound to 127.0.0.1 for local development unless you understand the risk. If you bind to a network interface, set TERMINAL_TOKEN and avoid exposing the server to untrusted networks.