andy/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: rewrite for Nexus Terminal

Browse Source
This commit is contained in:
Andy Dixon
2026-10-11 17:52:35 +01:00
parent cc42a9086d
commit 8c646e7176
5 changed files with 613 additions and 505 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-manual.md
+320 -168
View File
@@ -1,4 +1,4 @@
# Alchementary Link User Manual
# Nexus Terminal User Manual
## Contents
@@ -8,14 +8,16 @@
4. Connection types
5. Tabs and split panes
6. Terminal actions and search
7. Snippets and broadcast input
7. Snippets, broadcast input and triggers
8. SFTP file browser
9. Drag-and-drop uploads and paste
10. Session recordings
11. Leviathan binary workbench
10. Port forwards
11. Session recordings
12. Security and credentials
13. Settings
14. Troubleshooting
13. Import and export
14. Settings and updates
15. Data locations and migration from Alchementary Link
16. Troubleshooting
---
@@ -23,26 +25,35 @@
### Launch and connect
- Start Alchementary Link.
- Click **New** in the sidebar, choose a protocol, and fill in the profile details.
- Click **Connect** to open a session in a new tab.
- 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. This starts a one-off session without saving a profile.
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
- **Sidebar**: Profiles grouped by folders or tags, with search at the top.
- **Tab bar**: One tab per session with status indicators, badges, and quick actions.
- **Workspace**: The active terminal or viewer; split panes appear here.
- **Status bar**: Connection state and session details.
- **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.
Screenshot: Main window with sidebar, tab bar, and active terminal.
Tip: You can drag the divider between split panes to rebalance space.
Notifications appear as toasts in the top-right corner and dismiss themselves after a few seconds; click **×** to dismiss one early.
---
@@ -50,22 +61,39 @@ Tip: You can drag the divider between split panes to rebalance space.
### Create a new profile
1. Click **New** in the sidebar.
2. Choose the protocol (SSH, Telnet, RAW, VNC, or GitHub).
3. Fill in the required fields and optional settings.
4. Save and connect.
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.
Screenshot: New profile form with protocol selector and connection fields.
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.
### Edit, duplicate, or delete
The **Group** field suggests existing groups; type a new name to create one.
Right-click a profile in the sidebar to edit, duplicate, or delete it. You can also click the pencil icon on hover, or double-click the item to edit.
### Edit, duplicate, favourite, export or delete
### Folders, tags, and favourites
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.
Use folders and tags to organise profiles. Mark profiles as favourites for quick access.
### Bulk actions
Tip: Use the search box to filter profiles by name, host, or tag.
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**.
---
@@ -73,105 +101,190 @@ Tip: Use the search box to filter profiles by name, host, or tag.
### SSH
- Password, public key, keyboard-interactive, SSH agent, and TOTP/2FA.
- Jump hosts, port forwarding, proxy support, and auto-reconnect.
- Built-in SFTP browser and session recording.
- **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
- Option negotiation, encoding, local echo, and line endings.
- Auto-login scripts and auto-reconnect.
- **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
- Text, hex, and split views for binary-safe data.
- Payload presets and configurable encoding and line endings.
- **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.
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
- Remote desktop viewer embedded in the Link workspace.
- Password prompt and saved-password modes.
- View-only mode, scale-to-fit, shared sessions, and quality controls.
- Optional SSH tunnel for safer VNC transport.
- **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.
Use SSH tunnelling for VNC whenever possible. Direct VNC is useful on trusted or isolated networks, but many classic VNC deployments do not provide strong transport encryption.
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**. 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
- Browse repositories by organisation.
- Sorted by most recent activity.
- **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.
- **Pin** important sessions to keep them at the front.
- **Scroll** the tab bar with the scrollbar or mouse wheel/trackpad when many tabs are open.
- **Hover** a tab to see the full name and, for connected sessions, the connection start time.
- **Close** tabs with the close button on the left side of each tab. Leviathan tool tabs close without a disconnect confirmation.
- **Split** the workspace vertically or horizontally to view multiple sessions at once.
- **Broadcast** input to multiple connected sessions when needed.
- **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.
Screenshot: Tab bar with pinned sessions and split panes.
### Split panes
Tip: Pinned tabs stay at the front so key systems never get buried.
- **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
- Copy and Paste
- Select All
- Find
- Send snippet
- Clear and reset
Screenshot: Terminal context menu and search bar.
- 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 case sensitivity and regular expressions as needed.
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 and broadcast input
## 7. Snippets, broadcast input and triggers
### Snippets
Open the snippet library with **Cmd+Shift+S** (macOS) or **Ctrl+Shift+S** (Windows/Linux) and save frequently-used commands. Send a snippet to the active session with one click.
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.
Screenshot: Snippet library with search and folder grouping.
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). While active, all input is sent to every connected session.
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. You can:
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.
- Upload, download, rename, and delete files.
- Refresh and create folders.
- 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.
The browser runs inside the SSH session and shows remote contents in a side panel.
Screenshot: SFTP browser open alongside the terminal.
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) into an active terminal, Alchementary Link asks whether to:
When you drop file(s) onto an active terminal, Nexus Terminal asks whether to:
- **Upload** to a chosen remote directory, or
- **Upload to current directory** — choose a remote directory (SSH sessions only), or
- **Paste contents** into the terminal as if typed.
### Upload directory picker
@@ -181,163 +294,202 @@ 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. You can also use the keyboard:
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.
Screenshot: Upload directory picker with permissions badges.
Tip: Use the filter box to jump quickly to common folders.
---
## 10. Session recordings
## 10. Port forwards
Toggle recording with **Cmd+Shift+R** (macOS) or **Ctrl+Shift+R** (Windows/Linux). Recordings are saved as asciicast v2 files and can be replayed from the recordings panel.
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:
Screenshot: Recordings list with playback controls.
- **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. Leviathan binary workbench
## 11. Session recordings
Leviathan is the integrated binary-analysis and editing workspace inside Alchementary Link. It is useful for firmware images, unknown binaries, archives, captures, embedded files, suspicious documents, and audio spectrogram experiments.
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.
### Switching to Leviathan
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.
Click **Leviathan** in the top-left sidebar header. The normal connection list changes into a tool list. Click **Alchementary Link** to return to saved servers and groups.
Use **Load** to select a local file. The selected file becomes the current Leviathan working document. Use **Save** to write the patched working copy to a chosen destination.
Leviathan tools open as regular tabs. You can open multiple tool tabs at once, switch between them, and close them without a connection-disconnect confirmation.
### Hex Editor
The Hex Editor is the primary byte-level view.
- Choose 16 or 32 bytes per row.
- Edit byte cells directly; typing two hex digits advances to the next byte.
- The ASCII preview updates as bytes are edited.
- Paste hex runs such as `de ad be ef` or `deadbeef` into consecutive cells.
- Use Search to find strings or hex values, then move through matches with previous/next.
- Undo, redo, or revert edits from the Leviathan panel header.
### Triage tools
- **Overview**: first-pass summary across hashes, entropy, strings, indicators, and carve candidates.
- **Hashes**: CRC32, MD5, SHA-1, SHA-256, and SHA-512.
- **Entropy**: graph entropy across the whole file; select a region to open that range in a new Hex Editor tab.
- **Strings**: ASCII and UTF-16 string extraction.
- **IOCs**: URLs, domains, paths, hashes, and other indicators.
- **Search** and **Multi-search**: text, hex, and regular-expression matching.
### Structure and recovery tools
- **Structures** parses common formats such as PE, ELF, Mach-O, ZIP, images, RIFF, ASN.1, and certificates.
- **Disasm** provides heuristic disassembly for common CPU families and raw byte fallback where decoding is not implemented.
- **PDF** inspects objects, streams, xrefs, and suspicious surfaces.
- **SquashFS** inspects filesystem superblocks and metadata; non-SquashFS input shows a human-readable bad-magic error.
- **Carve** and **BinSnoop** scan for embedded files and signatures and can export discovered files or ranges.
- **Keys**, **Timestamps**, **Stego**, and **Metadata** help recover common artefacts from binaries and containers.
### Editing, transforms, and cases
- **Patch Plan** validates patch scripts without modifying the working copy.
- **Patch Apply** applies validated patch scripts.
- **Transforms** runs pipelines such as hex, Base64, URL, XOR, inflate, and cipher transforms over selected data.
- **Rules** runs YARA-like scans over the current document.
- **Case Export** packages investigation artefacts from the working document.
### Spectrogram tools
- **Spectrogram Encode** converts an image into WAV audio so the image appears in a spectrogram.
- It can also insert an encoded image into an existing WAV or MP3 carrier.
- **Spectrogram View** renders WAV or MP3 audio as a spectrogram image.
- Controls include FFT size, height, maximum width, aspect ratio, frequency range, brightness, and contrast.
### Large file behaviour
Leviathan keeps loaded files file-backed where possible and writes patched working copies in chunks. Some tools still need bounded in-memory buffers because the underlying parser or decoder works on complete byte slices; those tools reject oversized inputs with a clear message rather than trying to allocate unbounded memory.
Playback starts automatically and has play/pause, restart, a seek bar with elapsed and total time, and speed control.
---
## 12. Security and credentials
Alchementary Link stores credentials securely:
### Where credentials are stored
- **OS keychain first** (Keychain, Secret Service, or Credential Manager).
- **Encrypted vault** fallback using AES-256-GCM with Argon2id.
- **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**: only accept previously saved fingerprints.
- **Ask**: prompt before trusting a new host key.
- **Accept new**: trust first-time keys, reject changes.
- **Insecure**: accept any key (not recommended).
- **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 auto-fill verification codes during SSH authentication.
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.
Screenshot: TOTP configuration in the profile editor.
### 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. Settings
## 13. Import and export
Open settings with **Cmd+,** (macOS) or **Ctrl+,** (Windows/Linux) and configure:
- Terminal themes and fonts
- Default behaviours
- Secrets and vault settings
- Recording and shortcut preferences
Screenshot: Settings panel with appearance and security options.
- **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. Troubleshooting
## 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 terminal is blurred and shows a **DISCONNECTED** overlay when the connection drops.
- 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 SSH session is connected.
### 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 the profile is set to saved, session-only, or ask-every-time mode.
- If using an SSH tunnel, verify the tunnel host, username, authentication method, and SSH host key policy.
- If direct VNC is enabled, test from a trusted network first and prefer an SSH tunnel for untrusted networks.
### Leviathan cannot load or save a file
- Check that the file still exists and that your user account can read it.
- When saving, choose a writable destination and avoid overwriting a file that another process has locked.
- Some tools enforce explicit size limits for safety. If a tool rejects an oversized input, try selecting a smaller range or using a tool that works on the file-backed document.
- 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 auto-reconnect settings in the profile.
- 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.
- Avoid heavy UI resizing during initial connection.
- 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.