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 self-hosted web terminal for machines you control, built for a single owner. It is not a hosted shell service, 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, select direct connectivity for stable reachable servers or outbound connectivity for NAT/mobile hosts, enter the main server URL, and log in once from the CLI. The server then 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.

The full main/secondary setup flow and nginx/TLS automation are described in docs/onboarding.md (included in the package).

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 every secondary server from one browser UI. Each server keeps its own workspaces, tabs, split panes, files, and layout.
• Persistent real shells: real host PTYs with workspaces, tabs, and split panes. Closed terminals detach instead of dying, and shells survive NTerminal restarts when tmux is available.
• Codex / Claude aware panes: panes running Codex or Claude get a transcript history viewer with server-side search, a subagent viewer, working/unread activity colors, and completion notifications.
• Provider accounts and hooks: save several Codex or Claude logins per server, switch between them, and check weekly usage. Optional lifecycle hooks give more reliable session and activity signals.
• Secure personal access: password plus TOTP, trusted devices and networks, IP-aware session checks, and origin checks around terminal/file mutation routes.
• Files, uploads, and attachments: browse and edit files in the selected pane's folder, drop files or folders into the terminal, attach files to a Compose message for an agent to read, or open the pane in a browser VS Code (code-server add-on).
• Works on phones and tablets: pane switcher, terminal key bar, and installable PWA with push notifications.
• Guided npm deployment: install with npm, run nterminal onboarding, keep runtime state under ~/.nterminal, and update every server from the UI.

Feature Details

Servers And Workspaces

• Sidebar server switching does not tear down inactive server workspaces.
• Each server has named workspaces, each with a default folder and its own tabs and panes. Workspaces can be renamed, reordered, and deleted.
• Server cards can show CPU, memory, disk, and swap usage with percentages and absolute values, in compact or detailed mode. High usage is highlighted.
• Secondary servers connect directly (main reaches them over the network) or outbound (the secondary keeps an authenticated WSS connection to main, for NAT, mobile, or changing IPs, with no inbound port).
• The Server information dialog shows the server role, its external IPv4, its favorite tabs, and its processes grouped by project folder with CPU and memory totals.
• Fleet updates check the npm registry, 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.
• Tabs show a green dot while working and a blue unread badge when output finished in the background; workspaces and favorites show the same state.
• Favorite tabs: star any tab, then open the favorites dialog (Ctrl+Alt+F) to jump to it on any server. A favorite whose tab was closed is recreated in its saved folder.
• Scroll progress, jump-to-bottom, mobile drag handles, and follow-tail behavior keep large outputs usable.
• Workspace shortcuts use Control-based keys and can be rebound in Settings (see docs/features.md).

Codex / Claude History And Subagents

• Supported Codex/Claude panes open JSONL transcript history (View history, Alt+H) from ~/.codex/sessions or ~/.claude/projects, with Markdown rendering, optional tool output, a prompt list, and scroll-to-load older entries.
• Search runs on the server from newest to oldest, including records not yet loaded in the viewer, and selecting a result loads the history around it.
• History is attached only when NTerminal can identify the backing session unambiguously. When several sessions are plausible, choose one from the session menu; this never changes the running CLI.
• A private, bounded disk cache reuses parsed conversation records across views and searches, and the history layout adapts to narrow panes.
• The subagent viewer (View agents, Alt+A) lists the subagents a session launched, with their state, and opens each one's conversation. It covers Claude subagents, Codex child threads, and codex exec runs started from a Claude session; nested subagents fold under their parent.

Provider Accounts And Hooks

• Open a server's Codex or Claude account dialog from the provider buttons on its server card.
• Each server keeps its own encrypted credential vault. Save several accounts, switch with Use, add one without leaving the dialog, and refresh credentials. Accounts are named after the signed-in email by default; click a name to rename it (the email stays visible under a custom name). Add account runs the official CLI login on the server and shows its sign-in link (open it or copy it to any browser) plus, for Codex, the one-time device code; for Claude, paste the code the page shows back into the dialog. Running Codex/Claude sessions are listed for reference but do not block a switch; they keep their current account until restarted (Exit all sessions stops them). Refreshing the active account waits until its CLI has exited. The active account is also backed up in the vault, so if a running session writes its old account back over the login file, the dialog says so and Use restores the other account. A saved login the provider revoked or let expire shows Re-login required, with a Sign in again button; the server card's provider icon gets a small marker.
• The dialog shows access-token expiry, weekly and session usage remaining, reset times, and the last refresh result. Usage checks are read-only.
• Optional provider lifecycle hooks (Linux, see docs/provider-hooks.md) can be installed or removed from the same dialog or with nterminal hooks. For Codex, confirming Install hooks also asks Codex to trust only NTerminal's own hooks, the same as approving them in /hooks. A separate Trust button remains available for earlier installations or retries.

Files, Uploads, And Editor

• The Files sidebar browses the selected pane's folder: view/edit text and Markdown, preview browser-supported files, and create, rename, or delete entries. Saves reject stale overwrites.
• Drop files or folders onto the terminal to upload them into the active pane's folder. Folder drops preserve internal paths and never overwrite existing files. Batches queue safely, show progress, support cancel, and retry only failed files.
• Compose attachments: attach files to a Compose message by picker, drag-and-drop, or paste. They are stored privately under ~/.nterminal/attachments on the pane's server, and their paths are appended when the message is sent, so Codex, Claude, or another CLI can read them.
• Remote editor: the pane header can open the pane's folder in code-server (browser VS Code). NTerminal downloads and verifies the code-server release on first use (Linux x64/arm64) and stops idle instances.
• Terminal Ctrl+C copies selected text and falls through to SIGINT when nothing is selected; Ctrl+V pastes clipboard text or attaches clipboard images directly in Codex/Claude panes, without submitting the prompt.

Notifications

• In-app completion toasts appear when a Codex or Claude turn finishes in a pane you are not looking at. Plain shell commands finishing do not notify. Clicking a toast jumps to the server and pane that finished.
• Toasts can auto-dismiss, stay until dismissed, or play custom MP4/WebM videos chosen at random from the enabled set.
• OS notifications are available while the page is hidden, and the installed PWA can receive push notifications (HTTPS or localhost).

Mobile And PWA

• Split layouts on narrow screens show one pane at a time, with previous/next buttons and a switcher for terminals and editors.
• The mobile key bar exposes Ctrl, Esc, Tab, and arrows when needed.
• Touch scrolling controls are tuned for long terminal output.
• iPad home-screen metadata and icons are included.

Requirements

• Node.js 22.13.0 or newer.
• Linux or macOS.
• Native build tools required by node-pty.
• Optional tmux for PTY persistence across Node restarts.
• Provider hooks and the code-server add-on require Linux.

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 start | stop | restart
nterminal logs [-f] [N]
nterminal doctor
nterminal url
nterminal version
nterminal hooks status --provider codex
nterminal hooks install --provider claude
nterminal hooks trust --provider codex
nterminal uninstall --force

Run nterminal help for the full list. Updates run from Settings, not from a CLI command.

Documentation

These guides ship with the package: after npm install -g nterminal they are in the package's docs/ folder (npm root -g shows where global packages live).

• Onboarding (docs/onboarding.md): main/secondary setup, nginx, TLS, firewall, and package runtime setup.
• Configuration (docs/configuration.md): .env, environment variables, and deployment examples.
• Operations (docs/operations.md): service control, updates, clean uninstall, verification, and troubleshooting.
• Terminal History (docs/terminal-history.md): tmux scrollback, alternate buffer behavior, Codex/Claude JSONL history, search, and large-output ergonomics.
• Provider Hooks (docs/provider-hooks.md): optional Codex/Claude lifecycle hooks, Codex trust, and the nterminal hooks command.
• Features (docs/features.md): workspaces, accounts, files, uploads, attachments, notifications, mobile controls, keyboard shortcuts, and PWA behavior.
• Security (SECURITY.md): 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.
• The built-in file editor is not an IDE. Full editing needs the optional code-server add-on, which is Linux-only.

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. The full text is in the LICENSE file included in the package.