nexus/docs/user-manual.md

Nexus Terminal User Manual

Contents

1. Getting started
2. The interface at a glance
3. Creating and managing profiles
4. Connection types
5. Tabs and split panes
6. Terminal actions and search
7. Snippets, broadcast input and triggers
8. SFTP file browser
9. Drag-and-drop uploads and paste
10. Port forwards
11. Session recordings
12. Security and credentials
13. Import and export
14. Settings and updates
15. Data locations and migration from Alchementary Link
16. Troubleshooting

---

1. Getting started

Launch and connect

• Start Nexus Terminal.
• Click + at the bottom of the sidebar (or press Cmd+N / Ctrl+N), choose a protocol, and fill in the profile details.
• Click Create & Connect to save the profile and open a session in a new tab, or Create to save it for later.
• Click a profile in the sidebar to connect to it.

Quick connect

Use Cmd+Shift+Q (macOS) or Ctrl+Shift+Q (Windows/Linux) to open a lightweight connect dialog. Choose SSH, Telnet, RAW, IRC or Serial, enter the host (or serial device), port, and username or nick where relevant, then press Enter. This starts a one-off session without saving a profile.

Local terminal

Click Local Machine at the top of the sidebar, choose File → Local terminal, or click Local on the welcome screen to open a shell on this computer. When the shell exits, the tab shows [Exited - press enter to restart]; press Enter to start a new shell in the same tab.

Command palette

Press Cmd+K / Ctrl+K, or click the search box in the title bar, to open the command palette. Type a few letters to find a connection, switch to a tab, create a profile, open a window, change theme, lock or unlock the secret store, or run a terminal action. Use Up/Down to move, Enter to run, and Esc to close.

---

2. The interface at a glance

• Title bar: the File, Session, View and Help menus, the active session's name and host, the command palette launcher, a light/dark toggle, and the window controls. Drag the title bar to move the window; double-click it to maximise.
• Sidebar: a search box, then Local Machine, ★ Favourites, Recent (the last five connections), one section per group, and Ungrouped (or All Connections when you have no groups). Sections collapse when you click their headers. The footer has buttons for New connection, Command palette, Import, Export, Recordings and Settings. Drag the sidebar edge to resize it.
• Tab strip: one tab per session, with a state dot, protocol badge, pin marker, activity dot and close button. SSH tabs also have a folder icon for SFTP. On the right are + (new connection) and the broadcast button.
• Workspace: the active terminal or viewer; split panes appear here. With no tabs open it shows a welcome screen with New Connection, Quick Connect and Local buttons.
• Right dock: the profile editor or the SFTP browser, resizable.
• Status bar: the active session's state and protocol, a REC marker while recording, latency for SSH sessions, a BROADCAST marker, the vault state (click it to open Security settings), the number of connected sessions, and an update notice when a new version is available.

Notifications appear as toasts in the top-right corner and dismiss themselves after a few seconds; click × to dismiss one early.

---

3. Creating and managing profiles

Create a new profile

1. Click + in the sidebar footer or on the tab strip, press Cmd+N / Ctrl+N, or right-click a group header and choose New connection in ….
2. Choose the protocol (SSH, Telnet, RAW TCP, GitHub, VNC, IRC or Serial) at the top of the editor. Switching protocol keeps the common fields.
3. Fill in the General section: Display Name, Host (or Device for serial), Port, Username, Group and Description.
4. Fill in the protocol sections and, for terminal protocols, the Terminal section (font family, font size 8–36, scrollback 0–100000 lines, cursor style).
5. Optionally add Tags (comma-separated) and Notes.
6. Click Create & Connect, or Create to save without connecting.

Click Test to check that the host and port are reachable; a toast reports the round-trip time. Fields with problems are highlighted when you save.

The Group field suggests existing groups; type a new name to create one.

Edit, duplicate, favourite, export or delete

Right-click a profile in the sidebar for Connect, Edit, Duplicate, Add to Favourites / Remove from Favourites, Export… and Delete. Double-click a profile to edit it. Deleting a profile also removes its saved credentials.

Bulk actions

Ctrl-click (Cmd-click on macOS) profiles to select several. A bar appears at the bottom of the sidebar with:

• Connect all
• Disconnect (asks first when Confirm on disconnect is on)
• Tags → Add tags… or Replace tags…
• Move group (leave the name empty to move to Ungrouped)
• Delete
• Clear (clear the selection)

Search

Type in the sidebar search box to fuzzy-search profiles by name, host, tag and protocol.

Already open?

If you connect to a profile that already has a live session, Nexus Terminal asks whether to Use Existing, open a New Connection, or Cancel.

---

4. Connection types

SSH

• Authentication: password, public key, keyboard-interactive and SSH agent. Choose which methods to try under Auth Methods, and tick Use SSH Agent for Authentication to use ssh-agent (Pageant or the OpenSSH agent on Windows).
• Key & Passphrase: choose a key from the suggestions (keys in ~/.ssh), click Browse, or type a full path (~ is not expanded). The editor checks that the file exists and is a private key.
• Host Verification: the host key policy (see section 12).
• Jump Hosts: one or more bastions, each with user, host, port and an optional key. Nexus Terminal tunnels through each hop in order.
• Port Forwarding: local and remote forwards, each with a bind address and port, destination, label and an Active box to start it on connect.
• Startup: a startup command and environment variables (KEY=VALUE, one per line).
• Login Script: expect-style steps (see below).
• SSH Agent: agent authentication and Forward Agent to Remote (like ssh -A).
• TOTP / 2FA: store a Base32 TOTP secret to answer two-factor prompts automatically. Click Test to show the current code, Save to store the secret, and Delete to remove it. Save the profile first.
• Proxy: none, SOCKS5 or HTTP CONNECT, with host, port and optional username and password. The proxy is used to reach the SSH server, or the first jump host.
• Advanced: terminal type, keepalive interval, max missed keepalives, compression, auto-reconnect and the maximum number of reconnect attempts (1–20).

The SFTP browser, port forwards and status-bar latency are available on SSH sessions.

Telnet

• Login: local echo and line mode.
• Terminal & Encoding: terminal type and encoding (UTF-8, ASCII or ISO 8859-1).
• Echo & Line Endings: LF, CR, CRLF or none.
• Negotiation: Debug Negotiation for troubleshooting option negotiation.
• Login Script and Reconnection settings.

Telnet sends everything in plain text. Avoid it for anything sensitive over an untrusted network.

RAW TCP

• Encoding & Framing: encoding (UTF-8, ASCII or Hex) and line ending.
• Display: show timestamps and show direction.
• Payload Presets: named payloads with a format (Text, Hex or Escaped) for quick sending.
• Timeouts & Reconnect: connect and read timeouts, and auto-reconnect.

A RAW session opens a viewer instead of a terminal:

• Text, Hex and Split views of everything sent and received.
• Pause / Resume, Clear, and Save (writes the capture as JSON).
• A send bar with a format selector (Text, Hex or Escaped), a Presets… menu, and quick buttons for EOT, ETX, LF, CR and NUL. Press Enter to send.

Serial

Serial profiles open a terminal on a local serial port.

• Device: pick the port from the list and click refresh after plugging in an adapter, or type a path such as /dev/ttyUSB0, /dev/cu.usbserial-… or COM3.
• Line Settings: baud rate (a preset from 300 to 1000000, or a custom value), data bits (5–8), parity (none, odd or even), stop bits (1 or 2) and flow control (none, XON/XOFF or RTS/CTS).
• Behaviour: line ending, encoding, local echo (for devices that don't echo), Assert DTR on connect, Assert RTS on connect, and auto-reconnect.

The defaults are 115200 baud, 8 data bits, no parity, 1 stop bit, no flow control, CR line endings, and DTR and RTS asserted.

While connected, right-click the tab to Send Break or toggle DTR and RTS. Telnet tabs also offer Send Break.

When the adapter is unplugged the session disconnects; with auto-reconnect on, the port is reopened when the device returns. Serial sessions support everything other terminals do: recording, triggers, broadcast, snippets, find and split panes.

VNC

• VNC Server: VNC host (defaults to the profile's Host), port, and password storage mode.
• Display: View Only, Scale to Fit, Shared Session and Quality (0-9).
• SSH Tunnel: carry VNC traffic through SSH, with host, port, username and password, public key or SSH agent authentication.

The viewer's toolbar shows the connection state and desktop size, and has buttons to switch between scaled and 1:1 display, refresh the screen, Paste Clipboard (send your local clipboard to the remote desktop) and Ctrl+Alt+Del. Text the remote desktop copies arrives on your local clipboard. Click the desktop to give it keyboard focus.

Use SSH tunnelling for VNC whenever possible. If a VNC profile has no tunnel, Nexus Terminal warns that the traffic is unencrypted and offers Connect Anyway, Edit Profile or Cancel.

IRC

• IRC: nick, real name, Use TLS (port 6697 for most TLS networks) and an optional server password.
• NickServ: identify on connect, with an optional account name and password.
• Rooms: rooms to join automatically, one per line or comma-separated.
• SSH Tunnel and Reconnection settings.

The IRC view has a Server tab and a tab per room or conversation, with a dot on tabs that have unread messages. Type messages or /commands in the composer (/join, /part, /msg, /me, /notice, /nick, /topic, /list, /names, /whois, /who, /raw, /quit, /help). Press Tab to complete a nick, or click a nick to mention it. The side panel lists joined rooms, a room browser with a filter (click a room to join it), and the users in the current room.

GitHub

• API: API base URL (https://api.github.com, or your GitHub Enterprise API URL) and personal access token storage. The token needs the repo scope.
• Refresh: refresh interval, 60–3600 seconds.

Repositories are grouped by owner or organisation and sorted by most recent activity. Each card shows Private, Fork and Archived badges, language, stars, description, and the last commit and committer. Use the filter box to narrow the list, Refresh now to update it, Visit to open a repository in your browser, and ZIP to download an archive.

---

5. Tabs and split panes

• Reorder tabs by dragging them, or right-click and choose Move Left / Move Right.
• Pin important sessions from the tab's right-click menu; pinned tabs stay at the front.
• Rename, Duplicate (open another session to the same profile) and Reconnect from the right-click menu.
• Scroll the tab strip with the mouse wheel or trackpad when many tabs are open.
• Hover a tab to see its name, host, state and, for connected sessions, the connection start time.
• Close a tab with its ×, Cmd+W / Ctrl+W, or Close in the right-click menu. When Confirm on close is on, closing a connected tab asks first (GitHub tabs close straight away).
• Switch tabs with Cmd+Tab / Ctrl+Tab, Cmd+Shift+Tab / Ctrl+Shift+Tab, or Cmd+1–9 / Ctrl+1–9.
• A dot on a background tab means it has new output.

Split panes

• Cmd+Shift+D / Ctrl+Shift+D splits the focused pane to the right (side by side).
• Cmd+Shift+E / Ctrl+Shift+E splits it downwards (top and bottom).
• Split Right and Split Down are also in the Session menu, the terminal's right-click menu and the command palette.

A new pane offers Local Machine and your terminal profiles (SSH, Telnet and Serial); click one to open it in that pane. Drag a divider to resize panes. Click × on a pane's header to close it; its neighbour takes the space. Closing the tab closes every pane in it.

---

6. Terminal actions and search

Keyboard and mouse

• Copy: select text and press Cmd+C / Ctrl+C. With nothing selected, Ctrl+C sends an interrupt as usual.
• Paste: Cmd+V / Ctrl+V. Pastes are bracketed when the remote application asks for it.
• Select: drag to select, double-click for a word, triple-click for a line, Shift-click to extend.
• Links: hold Cmd / Ctrl and click a web link to open it in your browser.
• Scroll: the mouse wheel, or Shift+PageUp, Shift+PageDown, Shift+Home and Shift+End. On the alternate screen (for example in tmux, screen, byobu or less) the wheel sends arrow keys instead.
• Applications that use the mouse (such as htop, vim or tmux with mouse mode) receive mouse clicks and the wheel directly.

Context menu

Right-click in the terminal for:

• Copy and Paste
• Select All
• Find
• Send Snippet
• Port Forwards (SSH)
• Split Right and Split Down
• Export Output (save the whole scrollback as a text file)
• Clear and Reset

Search

Press Cmd+F (macOS) or Ctrl+F (Windows/Linux) to search in the active terminal. Toggle Aa for case-sensitive matching and .* for regular expressions. The bar shows "n of total"; press Enter for the next match, Shift+Enter for the previous one, and Esc to close.

Disconnects and errors

When a session drops, the pane is dimmed and shows a Disconnected (or Connection error) card with Reconnect and Close. While auto-reconnect is running it shows Reconnecting… with a Cancel button, and a toast shows the attempt number and delay.

If a connection fails because of authentication or a host key, a guided dialog explains what happened and offers Retry, Edit Profile, Known Hosts (for host-key errors) and Close.

---

7. Snippets, broadcast input and triggers

Snippets

Open the snippet library with Cmd+Shift+S (macOS) or Ctrl+Shift+S (Windows/Linux), from the Session menu, or with Send Snippet in the terminal's right-click menu. Create snippets with a name, description, command and folder, search them, and click Send to Session to type the command into the active session followed by Enter.

Snippets can use variables:

• {{hostname}}, {{date}}, {{time}} and {{timestamp}} are filled in automatically.
• Any other {{name}} is asked for when you send the snippet.

Broadcast input

Toggle broadcast mode with Cmd+Shift+B (macOS) or Ctrl+Shift+B (Windows/Linux), the broadcast button on the tab strip, or the Session menu. While it is on, everything you type is also sent to every other connected terminal session, and the status bar shows BROADCAST.

To broadcast to only some sessions, right-click the broadcast button (or choose Session → Broadcast targets…), tick the sessions you want, and click Apply & Enable.

Trigger rules

Open Trigger Rules from the Session menu or the command palette. Each rule has a name, a pattern (plain text or regular expression), a case-sensitive option, an enabled switch and an action:

• Notify: show a toast.
• Highlight tab: briefly outline the pane.
• Notify + Highlight: both.
• Sound: ask the operating system for attention (for example, a bouncing dock icon or flashing taskbar button) and show a toast.

Rules are checked against each complete line of terminal output, with colour codes removed.

---

8. SFTP file browser

Open the file browser with the folder icon on an SSH tab, or Session → SFTP browser. It opens in the right dock beside the terminal. You can:

• Navigate folders using the breadcrumb trail, the .. entry, or Go to path.
• Upload files, and download one or more selected files to a folder you choose.
• Rename a single item, and delete one or more items (with confirmation).
• Create folders and refresh the listing.
• Bookmark the current folder with the star button; bookmarks are kept per profile.
• Watch transfers and their progress in the transfer list.

Ctrl-click (Cmd-click) or Shift-click to select several items. Drag the dock edge to resize it.

---

9. Drag-and-drop uploads and paste

When you drop file(s) onto an active terminal, Nexus Terminal asks whether to:

• Upload to current directory — choose a remote directory (SSH sessions only), or
• Paste contents into the terminal as if typed.

Upload directory picker

The picker looks like the SFTP browser and lists remote folders only. It shows:

• READ ONLY for folders you cannot write to.
• NO READ for folders you cannot access.

Use the filter box to narrow the list, and the breadcrumb trail or Up button to move around. Use this folder is disabled when the folder is not writable. You can also use the keyboard:

• Up/Down: move selection
• Enter: choose the selected folder
• Backspace: go up a folder (when the filter is empty)
• Escape: cancel

If the SFTP browser is already open, the picker starts in the same directory.

Tip: Use the filter box to jump quickly to common folders.

---

10. Port forwards

Forwards saved in an SSH profile start when the session connects. To manage forwards on a live SSH session, choose Port Forwards from the terminal's right-click menu or Session → Port forwards. The dialog lists active forwards (marked L for local or R for remote) with a stop button, and lets you start a new one:

• Local →: listen on a local bind address and port, and forward to a destination reachable from the server.
• Remote ←: ask the server to listen, and forward connections back to a destination reachable from this computer.

Toasts report when a forward starts, stops or fails.

---

11. Session recordings

Toggle recording with Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux), or Session → Toggle recording. A red dot appears on the tab and REC in the status bar. Recordings are saved as asciicast v2 files.

Open the recordings browser from the sidebar footer, the Session menu or the command palette. It shows how many recordings you have and how much space they use, lets you play or delete each one, and has Clean up for removing recordings older than 7, 30 or 90 days, or keeping the total under 1 GB or 5 GB.

Playback starts automatically and has play/pause, restart, a seek bar with elapsed and total time, and speed control.

---

12. Security and credentials

Where credentials are stored

• OS keychain first (macOS Keychain, Linux Secret Service or Windows Credential Manager).
• Encrypted vault fallback, using AES-256-GCM with an Argon2id-derived key (128 MiB of memory, which makes brute-force attacks expensive).

If the keychain is unavailable, or refuses to store a secret, credentials go to the vault. Set the vault up in Settings → Security with Initialise Secret Store; the master-password dialog shows a strength meter (Weak, Fair, Good, Strong) and asks you to confirm the password. Unlock and lock it from the same page, the command palette, or by clicking the vault state in the status bar. The vault is locked again when Nexus Terminal quits.

Without the master password, credentials in the vault cannot be recovered.

Secret modes

Each password, passphrase, token or TOTP secret has its own mode:

• Save securely: stored in the keychain or vault and used automatically.
• Remember for this session: asked for once, kept in memory for that session, never written to disk.
• Ask every time: asked for on every connection.

When a session needs a credential it doesn't have, a prompt appears; press Esc or Cancel to abandon the connection.

Host key verification

Choose one of the following policies per SSH profile:

• Strict (known hosts only): only accept previously saved host keys.
• Ask on new or changed keys: prompt before trusting a new host key; the dialog shows the key type and fingerprint with Accept & Save and Reject.
• Accept new, reject changed: trust first-time keys automatically.
• Insecure (accept anything): accept any key (not recommended).

Under every policy except Insecure, a key that differs from the saved one is rejected. Nexus Terminal keeps its own known-hosts list and does not read ~/.ssh/known_hosts. Review and remove entries in Settings → Known Hosts; click a fingerprint to copy it.

TOTP / 2FA

Store a TOTP secret in the profile editor to answer verification-code prompts automatically during SSH keyboard-interactive authentication. Secrets are stored in the keychain or vault, never in the profile database.

SSH key manager

Open SSH key manager from the Session menu or the command palette. It lists key pairs in ~/.ssh with their type, lets you copy a public key to the clipboard or delete a pair, and generates new Ed25519, RSA (2048 or 4096 bits) or ECDSA keys with an optional passphrase. Key generation uses the ssh-keygen program.

Audit log

Connections, disconnections, profile changes, credential access, imports and exports are recorded in an audit log in the database. Secrets are never written to it.

---

13. Import and export

• Encrypted export: File → Export profiles…, the sidebar footer, the command palette, or Export… on a profile's right-click menu. Choose the profiles, set a password and save a .nexus file. Credentials saved in the keychain or vault are not included.
• Encrypted import: File → Import profiles… or the sidebar footer. Choose a .nexus file (or a .link file from Alchementary Link), enter its password, and choose what happens when a profile already exists: Skip existing, Overwrite existing or Create duplicates.
• JSON export and import: Export Profiles (JSON) and Import Profiles (JSON) in the command palette. JSON export includes every profile; tick Include secrets to keep inline proxy passwords and TOTP secrets, which are otherwise removed.
• OpenSSH config: File → Import ~/.ssh/config or Settings → About → Import ~/.ssh/config creates profiles from your Host blocks, including hostnames, usernames, ports, identity files and jump hosts.

---

14. Settings and updates

Open settings with Cmd+, (macOS) or Ctrl+, (Windows/Linux), the sidebar footer, or File → Settings. Click Save to apply changes.

• General: app theme (Pro, Midnight or Light), default protocol, confirm on close, confirm on disconnect, status bar, sidebar width, and local shell (leave empty for the system default; Browse… to pick one).
• Terminal: colour scheme, font family, font size, scrollback lines and cursor style. These are the defaults for new profiles; profiles can override them.
• Security: keychain and vault status; initialise, unlock or lock the secret store.
• Known Hosts: saved host keys with first-seen and last-seen times, and Remove.
• Help: built-in help topics, including connection types, shortcuts and troubleshooting.
• About: version, Check for Updates, and Import ~/.ssh/config.

The app theme and terminal colour scheme can also be changed from the View menu, and the light/dark button in the title bar.

Updates

Nexus Terminal checks for a new version once at launch. When one is available, the status bar shows Update available; click it to open Settings → About, which shows the current and latest versions, release notes and a View release button. Nothing is downloaded or installed automatically.

---

15. Data locations and migration from Alchementary Link

Data locations

OS	Data directory
macOS	~/Library/Application Support/NexusTerminal
Windows	%APPDATA%\NexusTerminal
Linux	$XDG_CONFIG_HOME/NexusTerminal (usually ~/.config/NexusTerminal)

The directory holds:

• nexus.db — profiles, known hosts, preferences, snippets, IRC channel state and the audit log (SQLite)
• vault/vault.json — the encrypted vault
• recordings/ — session recordings
• triggers.json — trigger rules
• sftp-bookmarks.json — SFTP bookmarks

Credentials saved in the OS keychain are stored under the service name NexusTerminal.

Migrating from Alchementary Link

On first run, if Nexus Terminal has no database yet and an Alchementary Link data directory (AlchementaryLink, in the same parent folder) exists, Nexus Terminal copies link.db to nexus.db, along with the vault/ and recordings/ directories, and shows a toast saying where the data came from. The Alchementary Link directory is left untouched.

• If a NexusTerminal/nexus.db already exists (for example from a version before the Alchementary Link rebrand), it is used as-is and nothing is copied.
• Keychain entries saved under AlchementaryLink are found the first time they are needed and copied to NexusTerminal. The old entries are not deleted.
• Your vault master password is unchanged.
• Trigger rules and SFTP bookmarks from Alchementary Link are not migrated; recreate them in Nexus Terminal.

---

16. Troubleshooting

Session shows as disconnected

• The pane is dimmed and shows a Disconnected overlay when the connection drops.
• Click Reconnect to reopen the session with the same profile.

Authentication fails

• Check the username, password, key path and the auth methods ticked in the profile.
• If the key has a passphrase, check the passphrase mode.
• If the server uses two-factor prompts, check the TOTP secret with Test and make sure your system clock is accurate.

"Host key verification failed"

The server's key differs from the one saved earlier. This can happen when a server is reinstalled, but it can also indicate an attack. If you're certain it's safe, open Settings → Known Hosts, remove the entry, and reconnect.

Upload fails or is greyed out

• Check the folder is writable; READ ONLY indicates no write permission.
• Confirm the session is connected over SSH; upload isn't available for other protocols.

Cannot read a folder

• NO READ indicates insufficient permissions.
• Try a parent folder or check remote access controls.

Serial port won't open

• Check the device path and that the adapter is plugged in; refresh the device list in the editor.
• Permission denied on Linux: add your user to the dialout group (uucp on some distributions), then log out and back in.
• On macOS, use the /dev/cu.* device rather than /dev/tty.*.
• Port is in use by another program: close any other program that has the port open, such as screen, minicom or an IDE serial monitor.
• Garbled output usually means the baud rate, parity or stop bits don't match the device.

VNC will not connect

• Confirm the VNC host and port are correct. The common VNC port is 5900 plus the display number.
• If using a password, check whether it is set to save securely, remember for this session, or ask every time.
• If using an SSH tunnel, verify the tunnel host, username, authentication method, private key and SSH host key policy.
• If direct VNC is enabled, test from a trusted network first and prefer an SSH tunnel for untrusted networks.

The secret store is locked

If a saved credential isn't used, the vault may be locked. Click the vault state in the status bar, or open Settings → Security, and unlock it.

Session keeps reconnecting

• Check network stability and credentials.
• Review the auto-reconnect settings in the profile. Reconnection backs off exponentially (1 s, 2 s, 4 s … up to 30 s) and stops after the maximum number of attempts.

Terminal size looks wrong

• Resize the window or drag a split divider; the terminal re-fits automatically.
• Try disconnecting and reconnecting the session.
• Some older servers don't support modern terminal features; try a different terminal type in the profile.

Trying things safely

To try something without touching your real data, start Nexus Terminal with --data-dir DIR to use a different data directory.