Nexus Terminal

A cross-platform desktop client for SSH, Telnet, RAW TCP, and GitHub — with encrypted credential storage and a dark Material-inspired interface.

Built with Wails v2 (Go backend, HTML/CSS/JS frontend, xterm.js terminal emulator).

---

Feature Highlights

• ✅ SSH with password, public key, keyboard-interactive, and SSH agent authentication
• ✅ Telnet with option negotiation, encoding, and local echo
• ✅ RAW TCP with text, hex, and split views
• ✅ GitHub repository browser grouped by organisation
• ✅ Tabbed multi-session with split panes, pinning, and reordering
• ✅ SFTP file browser overlay for SSH sessions
• ✅ Session recording and playback (asciicast v2)
• ✅ Encrypted vault (AES-256-GCM + Argon2id) and OS keychain integration
• ✅ Jump hosts, port forwarding, and SSH agent forwarding
• ✅ OpenSSH ~/.ssh/config import
• ✅ Encrypted profile export/import (.nexus format)
• ✅ 8 built-in colour themes and command palette
• ✅ Automatic update checking via GitHub Releases

---

Table of Contents

1. Getting Started
2. Keyboard Shortcuts
3. Connection Types
4. Security
5. Architecture
6. Building & Testing
7. Data Locations
8. Troubleshooting
9. Licence

---

Getting Started

What You'll Need

Tool	Version	Where to get it
Go	1.23+	golang.org/dl
Node.js	18+	nodejs.org
Wails CLI	v2	go install github.com/wailsapp/wails/v2/cmd/wails@latest

Linux users: you'll also need GTK and WebKit system libraries. Run wails doctor to check your setup.

Clone and Run

git clone https://github.com/andydixon/nexus-terminal.git
cd nexus-terminal
make deps    # install Go modules and npm packages
make dev     # launch with hot reload

The first build may take a minute or two while dependencies are fetched. Once it's running you'll see the Nexus Terminal window appear — ready to create your first connection profile.

---

Keyboard Shortcuts

All shortcuts use Cmd on macOS and Ctrl on Windows/Linux.

Shortcut	Action
Cmd + K	Open command palette
Cmd + N	New connection
Cmd + W	Close current tab
Cmd + Tab	Next tab
Cmd + Shift + Tab	Previous tab
Cmd + 1–9	Switch to tab by number
Cmd + ,	Open settings
Cmd + F	Find in terminal
Cmd + Shift + D	Split pane vertically
Cmd + Shift + E	Split pane horizontally
Cmd + Shift + R	Toggle session recording
F11	Toggle fullscreen (Windows/Linux)

---

Connection Types

SSH

Full-featured SSH client with support for:

• Authentication — password, public key, keyboard-interactive, SSH agent, and agent forwarding
• Jump hosts — connect through one or more bastion servers (multi-hop)
• Port forwarding — local, remote, and dynamic (SOCKS) tunnels
• SFTP — built-in file browser that slides open as a right-side overlay panel
• Host key verification — four policies: strict, ask, accept-new, and insecure
• Session recording — capture terminal output to asciicast v2 files for later playback
• OpenSSH config import — reads your existing ~/.ssh/config to create connection profiles

Telnet

• Option negotiation, configurable character encoding (UTF-8 and others)
• Local echo and line mode settings
• Configurable line endings

RAW TCP

• Binary-safe connection with three view modes: text, hex, and split (text + hex side by side)
• Payload presets for quick sending of common data
• Configurable character encoding and line endings
• Auto-reconnect on disconnection

GitHub

• Browse your repositories grouped by organisation
• Sorted by most recent commit, with automatic refresh
• Quick access from the sidebar alongside your other connections

---

Security

Nexus Terminal takes credential storage seriously. Your passwords and private key passphrases are never stored in plain text.

Two-Tier Credential Storage

1. OS keychain (preferred) — on macOS this is Keychain, on Linux it's Secret Service via D-Bus, and on Windows it's Credential Manager. If your system's keychain is available, Nexus Terminal uses it automatically.

2. Encrypted file vault (fallback) — if the OS keychain isn't available, credentials are stored in a local vault file encrypted with AES-256-GCM. You set a master password when creating the vault, and a strength metre helps you choose a good one.

How the Encryption Works

Detail	Value
Cipher	AES-256-GCM
Key derivation	Argon2id — 128 MiB memory, 3 iterations, 4 threads
Key length	256 bits (32 bytes)
Salt	32 random bytes (unique per vault)
Nonce	Random, prepended to ciphertext

Known Hosts

When you connect to an SSH server for the first time, Nexus Terminal can remember the server's fingerprint. You choose one of four policies per profile:

• Strict — reject any server whose key doesn't match a saved fingerprint
• Ask — prompt you to accept or reject unknown keys
• Accept new — automatically trust first-time connections, reject changes
• Insecure — accept any key (not recommended)

Profile Export & Import

Profiles can be exported as encrypted .nexus bundles (AES-256-GCM, same as the vault). By default, exports exclude secrets — passwords and passphrases are only included when you choose an encrypted export. Secrets are keyed internally by profile: profile:<uuid>:password, profile:<uuid>:passphrase.

---

Architecture

This section is aimed at developers who want to understand or contribute to the codebase.

Nexus Terminal is a Wails v2 desktop application: a Go backend handles all connection logic and data storage, whilst an HTML/CSS/JS frontend (rendered in a native webview) provides the interface.

internal/
  app/           — lifecycle bootstrap: opens database, initialises secrets, wires everything together
  api/           — single Service struct bound to Wails; every public method is callable from JS
  sessions/      — manages concurrent sessions; owns SSH/Telnet/RAW/GitHub client lifecycles
  storage/       — SQLite repository (WAL mode) with embedded sequential migrations
  secrets/       — two-tier credential storage (OS keychain + encrypted file vault)
  models/        — shared domain types, protocol configs, and defaults
  sshclient/     — SSH client with agent support
  telnetclient/  — Telnet with option negotiation
  rawclient/     — RAW TCP with hex encoding
  githubclient/  — GitHub API integration
  sftpclient/    — SFTP file operations
  sshconfig/     — OpenSSH config parser
  recording/     — asciicast v2 session recording
  exportimport/  — encrypted profile bundles (.nexus format)
  updater/       — GitHub Releases update checker
  knownhosts/    — SSH host key management
  validation/    — profile and protocol validation
  audit/         — timestamped audit logging

frontend/
  src/js/        — 15 IIFE-wrapped JS modules (no framework, no bundler)
  src/css/       — modular stylesheets with design tokens (tokens.css)

How the Frontend and Backend Communicate

• Frontend → Backend: calling window.go.api.Service.MethodName() returns a Promise. Every public method on the Go Service struct is available this way.
• Backend → Frontend: the Go side pushes events via wailsRuntime.EventsEmit(). The frontend listens with window.runtime.EventsOn().
• Interactive prompts (e.g. password requests, host key verification) use a request/response event pattern with a unique requestID, so the Go side can block on a channel until the user responds in the UI.

---

Building & Testing

Command	What it does
make deps	Install Go modules and npm packages
make build	Production build → build/bin/nexus-terminal.app (macOS)
make dev	Development mode with hot reload
make test	Run all Go tests (go test ./... -v -count=1)
make lint	Run golangci-lint

To run tests for a single package:

go test ./internal/storage/ -v -count=1 -run TestProfileCRUD

The frontend has no separate build step — npm run build (called by Wails) copies xterm vendor libraries from node_modules into the frontend source tree. All frontend assets are embedded at compile time.

---

Data Locations

Platform	Database	Vault	Recordings
macOS	~/Library/Application Support/NexusTerminal/nexus.db	.../vault	.../recordings/
Linux	~/.config/NexusTerminal/nexus.db	.../vault	.../recordings/
Windows	%APPDATA%\NexusTerminal\nexus.db	...\vault	...\recordings\

The database uses SQLite in WAL (Write-Ahead Logging) mode. Migrations are embedded at compile time and applied automatically on startup.

---

Troubleshooting

The app won't start on Linux You likely need GTK and WebKit system libraries. Run wails doctor to see what's missing, then install the packages it recommends for your distribution.

"Vault locked" on every launch If you're using the encrypted file vault (rather than the OS keychain), you'll need to enter your master password each time. If your system supports a keychain, Nexus Terminal will use it instead and you won't see this prompt.

SSH connection fails with "host key verification failed" Your profile's host key policy may be set to strict and the server's key has changed (or hasn't been saved yet). Open the profile settings and choose ask if you'd like to be prompted, or verify the server's key and update your known hosts.

Terminal text looks wrong or garbled Check the character encoding setting on the connection profile. Most modern servers use UTF-8, but some older systems may need a different encoding.

Build fails with "wails: command not found" Install the Wails CLI:

go install github.com/wailsapp/wails/v2/cmd/wails@latest

Make sure $GOPATH/bin (or $HOME/go/bin) is in your PATH.

---

Licence

This project is licensed under the MIT Licence. See LICENCE for details.

Bundle identifier: com.andydixon.nexusterminal Author: Andy Dixon — www.dixon.cx/nexus

---

_{Built with Wails, xterm.js, and Go.}