NTerminal

NTerminal turns your own machines into one secure browser workspace for real shells, Codex, Claude, files, and long-running terminal sessions.

NTerminal is a single-owner web terminal for machines you control. It is not a hosted shell product, not a SaaS app, and not a multi-user IDE.

How It Works

Browser
  -> Main Server
     -> Secondary Servers

• Main Server serves the browser UI, owns login/session security, stores the server list, and proxies terminal/file traffic to secondary servers.
• Secondary Servers run on additional machines and expose their local shells/files to the main server after guided onboarding.
• Each server is a normal Node.js process connected to real host PTYs through node-pty.

Quick Start

Install NTerminal on the machine that should become the main server, then run:

npm install -g nterminal
nterminal onboarding

Choose main. Onboarding writes .env, creates secrets, sets your password and TOTP, and can start the service.

To add another machine, install NTerminal there and run the same command:

npm install -g nterminal
nterminal onboarding

Choose secondary, enter the main server URL, log in once from the CLI, and the server registers itself in the main UI.

After onboarding finishes, open the URL printed in the final summary and log in with your password plus authenticator code.

See docs/onboarding.md for the full main/secondary setup flow and nginx/TLS automation.

Package installs keep runtime config and state under ~/.nterminal so package updates do not overwrite local sessions or secrets. Use a user-writable npm global prefix if you want in-app updates to run without sudo.

Run onboarding as the account that should own NTerminal. Do not use sudo nterminal onboarding; direct root-account installs are supported when root is the intended runtime user.

Major Features

• Multi-server workspace: manage the main server and all secondary servers from one browser UI, with separate tabs, panes, files, and layout state per server.
• Persistent real shells: run real host PTYs with tabs and split panes, soft-detach terminals without killing them, and keep shells alive across NTerminal restarts when tmux is available.
• Codex / Claude friendly history: scroll terminal output without driving TUI prompt history, load older tmux scrollback on demand, and open supported JSONL transcript history for Codex and Claude sessions.
• Secure personal access: password plus TOTP, trusted devices/networks, IP-aware session checks, and origin checks around terminal/file mutation routes.
• Files and uploads: browse the selected pane's cwd, view/edit text and Markdown, preview browser-supported files, and drag files or folders into the active terminal directory.
• Guided npm deployment: install with npm, run nterminal onboarding, keep runtime state under ~/.nterminal, and update servers from the UI.

Feature Details

Server Management

• Sidebar server switching does not tear down inactive server workspaces.
• Server cards can show CPU, memory, disk, and swap usage with percentages and absolute values.
• Compact and detailed server-list modes are available.
• High resource usage is highlighted directly in the server list.
• Fleet updates check npm registry versions, update secondary servers first, and update the main server last.
• Hourly update checks badge Settings and Updates when a newer package is available.

Terminal Workspace

• Refreshes and temporary WebSocket reconnects reattach to active PTYs.
• Closed tabs and panes become restorable detached terminals.
• A lightweight supervisor restarts the NTerminal Node process if it exits unexpectedly.
• Tab titles sync with tmux window names so labels survive detach/reattach cycles.
• Scroll progress, jump-to-bottom, mobile drag handles, and follow-tail behavior keep large outputs usable.

Transcript History

• Supported Codex/Claude panes can continue into JSONL transcript history from ~/.codex/sessions or ~/.claude/projects.
• The history viewer supports search, Markdown rendering, optional tool output, and scroll-to-load older transcript entries.
• Transcript history is attached only when NTerminal can identify the backing session unambiguously.

Files, Uploads, And Clipboard

• File saves reject stale overwrites when the file changed after opening.
• Folder drops preserve internal paths and avoid overwriting existing files.
• Multiple upload batches queue safely, show progress, support cancel, and retry failed files without duplicating successful uploads.
• Terminal Ctrl+C copies selected text and falls through to SIGINT when nothing is selected; Ctrl+V pastes clipboard text.

Notifications

• In-app completion toasts appear when background commands finish.
• Toasts can auto-dismiss, stay until dismissed, or use custom MP4/WebM videos.
• Settings can preview built-in/uploaded videos, enable/disable them, and randomly choose from the enabled set.
• Clicking a completion toast jumps back to the server and pane that finished.
• Optional OS notifications are available when the page is hidden.

Mobile And PWA

• iPad home-screen metadata and icons are included.
• Mobile terminal key bar exposes Ctrl, Esc, Tab, and arrows when needed.
• Split layouts on narrow screens can focus one pane at a time, with a bottom-sheet switcher for terminals and editors.
• Touch scrolling controls are tuned for long terminal output.

Requirements

• Node.js 22 or newer.
• Linux or macOS.
• Native build tools required by node-pty.
• Optional tmux for PTY persistence across Node restarts.

If PTY creation fails after a package install, rebuild the native module inside the global package:

npm explore -g nterminal -- npm rebuild node-pty --build-from-source

Common Commands

nterminal onboarding
nterminal status
nterminal logs
nterminal restart
nterminal uninstall --force

Documentation

• Onboarding: main/secondary setup, nginx, TLS, firewall, and package runtime setup.
• Configuration: .env, environment variables, and deployment examples.
• Operations: service control, updates, clean uninstall, verification, and troubleshooting.
• Terminal History: tmux scrollback, alternate buffer behavior, Codex/Claude JSONL history, and large-output ergonomics.
• Features: files, uploads, notifications, mobile controls, keyboard shortcuts, and PWA behavior.
• Security: supported security boundary and vulnerability reporting.

Limitations

• No multi-user accounts or roles.
• No container isolation for spawned shells by default.
• No recovery of live PTYs after an OS reboot.
• No Node-restart PTY persistence on hosts without tmux.
• No VS Code extension host, debugger, task runner, or Git UI.

Publication Notes

Keep local runtime files out of source control:

• .env
• .env.* except .env.example
• .nterminal/
• .claude/
• dist/
• logs
• test-results/
• playwright-report/

The npm package is constrained by package.json files and npm run pack:check. The source code is licensed under GPL-3.0-only.

Acknowledgements

NTerminal is inspired by Mansio and Leominal.

It reworks the persistent browser terminal idea around multi-server operation, OTP and IP-bound sessions, easier onboarding, and a more browser-native terminal experience with smooth scrollback and tab management, aiming to provide a more convenient and safer workspace for developers working across multiple remote servers.

License

NTerminal is licensed under GPL-3.0-only. See LICENSE.