nexus-terminal/doc/README_EN.md

---

中文 | English

📖 Overview

Nexus Terminal is a modern, feature-rich web-based SSH / RDP / VNC client dedicated to providing a highly customizable remote connection experience. A standalone desktop client is also available.

Maintained fork: Micah123321/nexus-terminal Upstream source project: Heavrnl/nexus-terminal

🧱 Project Structure

This repository uses an npm workspaces monorepo layout:

• packages/frontend: built with Vue 3, Vite, Pinia, xterm.js, and Monaco Editor; responsible for the web workspace, PWA, settings, and file editing experience
• packages/backend: built with Express, SQLite, WebSocket, and SSH/SFTP; responsible for authentication, connection management, notifications, and audit logs
• packages/remote-gateway: responsible for issuing RDP / VNC remote desktop tokens and bridging requests to guacd

✨ Features

• Manage SSH and SFTP connections with multiple tabs
• Support remote access to desktops via RDP/VNC protocol
• Support PWA and a standalone desktop client
• Utilizes Monaco Editor for online file editing
• Support suspending and resuming SSH sessions so long-running tasks stay alive
• Integrated multi-factor login security mechanisms, including human verification (hCaptcha, Google reCAPTCHA), two-factor authentication (2FA), and Passkey
• Highly customizable interface themes and layout styles
• Focus Switcher for moving between input components with configurable order and hotkeys
• Built-in simple Docker container management panel for easy container operations
• Supports IP whitelisting and blacklisting, with automatic banning for abnormal access
• Notification system and audit logs for login, credential, and system events
• Lightweight Node.js-based backend with low resource consumption
• Built-in heartbeat keep-alive mechanism to ensure stable connections

📸 Screenshots

Login Interface

---

Terminal Interface

---

Style Settings	Layout Settings	Settings Panel

🖥️ Desktop Client

Removed web-specific features such as various login verifications and session suspension.

https://github.com/Micah123321/nexus-terminal/releases/latest

🚀 Quick Start

1️⃣ Configure Environment

It is recommended to deploy in a Debian (AMD64 architecture) environment. Since I do not have an ARM device, compatibility with ARM is not guaranteed.

Create a new folder

mkdir ./nexus-terminal && cd ./nexus-terminal

---

Download the docker-compose.yml and .env files from the repository to your current directory.

wget https://raw.githubusercontent.com/Micah123321/nexus-terminal/refs/heads/main/docker-compose.yml -O docker-compose.yml && wget https://raw.githubusercontent.com/Micah123321/nexus-terminal/refs/heads/main/.env -O .env

⚠️ Note:

• For arm64 users, replace guacamole/guacd:latest with guacamole/guacd:1.6.0-RC1 in the docker-compose.yml file.
• For armv7 users, please refer to the additional notes below.

Configure nginx

location / {
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Range $http_range;
    proxy_set_header If-Range $http_if_range;
    proxy_redirect off;
    proxy_pass http://127.0.0.1:18111;
}

Configure IPv6 for Docker (optional — you can skip this if you don't use IPv6 to connect to the server).

Add the following content to /etc/docker/daemon.json:

{
  "ipv6": true,
  "fixed-cidr-v6": "fd00::/80",
  "ip6tables": true,
  "experimental": true
}

Then restart the Docker service:

sudo systemctl restart docker

2️⃣ Start the Service

docker compose up -d

3️⃣ Update

Note: Running with docker-compose does not require pulling the source code unless you plan to build it yourself. Simply execute the following commands in the project directory to update.

docker compose down

docker compose pull

docker compose up -d

📚 Usage Guide

Suspend Session Component

You can right-click in the SSH tab to select "Suspend Session" (long-press on mobile). Once suspended, even if the web connection is lost, the backend will automatically take over and keep the SSH connection active. You can resume the session at any time via the panel. This ensures that tasks such as compilation or long-running processes won’t be interrupted due to network issues.

Command Input Component

1. Tab Switching: When the command input box has focus, use Alt + ↑/↓ to switch between SSH session tabs, and Alt + ←/→ to switch between text editor tabs.
2. Command Sync (needs to be enabled in settings): When enabled, text entered in the command input box will be synchronized in real-time to the selected target input source. Use the ↑/↓ keys to select menu command items, then press Enter to send the selected command.

File Manager Component

1. Fixed Root Explorer: The file area now uses a single explorer tree rooted at /. Expanding a directory shows both child folders and files in the same tree.
2. Quick File Selection: When the file search box has focus, you can use the ↑/↓ keys to quickly select files.
3. Drag and Drop Upload: Supports dragging files or folders from outside the browser for uploading. Note: When uploading a large number of files or deeply nested folders, it is recommended to compress them first to avoid browser freezes.
4. Internal Drag and Drop: You can directly drag and drop files or folders within the file manager to move them.
5. Multiple Selection: Hold down the Ctrl or Shift key to select multiple files or folders.
6. Context Menu: Provides common file operations such as copy, paste, cut, delete, rename, and modify permissions.

Command History Component

1. View Full Command: When a historical command is too long and truncated, hover the mouse over the command to view the complete instruction content.

Terminal Component

1. Press Ctrl + Shift + C to copy, and Ctrl + Shift + V to paste.

General Operations

1. Zoom: In the terminal, file manager, text editor components, and quick command view, you can use Ctrl + mouse wheel to zoom.
2. Sidebar: The expanded sidebar can have its width adjusted by dragging.
3. Tab Bar: Right-clicking on the SSH tab bar or the file manager tab bar will open a context menu with the following options: Close, Close Tabs to the Left, Close Other Tabs, and Close Tabs to the Right.
4. Tab Group Fold Bar: You can directly click on the tab name in the view to rename the tab.
5. Automatic Reconnection: When the connection is lost, you can press Enter in the command input box or terminal, or click the same SSH connection in the connection list to trigger automatic reconnection.

Others

1. On mobile devices, you can zoom in or out on the terminal font using a two-finger gesture.
2. To enable Passkey login, set the RP_ID and RP_ORIGIN environment variables in the .env file.

⚠️ Notes

1. Dual File Managers: You can add two file manager components in the layout (experimental feature, may be unstable).
2. Multiple Text Editors: The functionality to add multiple text editors in the same layout has not yet been implemented.
3. For ARMv7 users, please use the docker-compose.yml provided here. Since Apache Guacamole does not provide an ARMv7-compatible image for guacd, the RDP/VNC feature has been disabled, and related images will not be pulled for now.
4. Since I don't have an ARM machine on hand, I haven't conducted actual testing, so unexpected bugs may occur during runtime.
5. For data backup, please back up the data folder in the directory yourself. This project does not provide any backup functionality.

🛠️ Development Notes

Common Commands

npm install
npm run dev --workspace=@nexus-terminal/frontend
npm run dev --workspace=@nexus-terminal/backend
npm run dev --workspace=@nexus-terminal/remote-gateway
npm run build --workspace=@nexus-terminal/frontend
npm run build --workspace=@nexus-terminal/backend
npm run build --workspace=@nexus-terminal/remote-gateway

Local Knowledge Base

The .helloagents/ directory stores the local knowledge base, module index, and plan packages used for collaboration and change tracking. It is not a runtime dependency, but when the project structure, feature set, or collaboration conventions change, the related entries should be kept in sync.

💐 Acknowledgements

• The preset theme schemes are based on the excellent iTerm2-Color-Schemes project.

📄 License

This project is licensed under the GPL-3.0 license. See the LICENSE file for details.