Connections & Sessions
This guide covers two related but distinct surfaces:
- Saved connections are reusable connection profiles: host, authentication, ProxyJump route, group, tags, and related configuration.
- Session Manager is the table-based workspace for finding, organizing, editing, importing, exporting, and opening those saved profiles.
Neither is the same as Active Sessions, which is the live connection tree shown while work is in progress.
Connection Configuration
Section titled “Connection Configuration”Creating Connections
Section titled “Creating Connections”Open the New Connection dialog from the sidebar (+ button) or the Session Manager toolbar.
Authentication Methods
Section titled “Authentication Methods”| Method | Description |
|---|---|
| Password | Prompted securely on connect — never stored in config files |
| SSH Key | RSA, Ed25519, ECDSA — file path or OS keychain |
| SSH Agent | Delegates to the running ssh-agent or macOS Keychain |
| Certificate | SSH certificate with optional CA verification |
| Keyboard Interactive | 2FA / OTP / PAM challenges on direct connections |
OxideTerm auto-detects the ~/.ssh/ directory and imports keys without configuration.
For direct connections, password auth can also fall back into keyboard-interactive prompts when the server requires it. For ProxyJump chains, explicit KeyboardInteractive auth is still limited today, so password/key/agent/certificate auth is the safer choice per hop.
Connection Options
Section titled “Connection Options”- Host / Port / Username — standard connection parameters
- Color — per-connection accent color for visual identification in the sidebar
- Group — organize into folders in the Session Manager
- Tags — freeform labels for filtering and searching
- ProxyJump (Jump Host) — chain through one or more bastion hosts
- Agent Forwarding — optionally forward your local SSH Agent to the remote host
ProxyJump: Multi-Hop SSH
Section titled “ProxyJump: Multi-Hop SSH”OxideTerm resolves jump chains using a Dijkstra shortest-path algorithm across your saved connection tree. You can chain through unlimited intermediate hosts:
Local Machine ──► Bastion A ──► Bastion B ──► Target Server- Intermediate sessions are opened automatically.
- Each hop is tracked individually in the Connection Pool.
- If any intermediate hop drops, its children are marked
link_downand cascade-reconnected.
Per-Hop Auth Notes
Section titled “Per-Hop Auth Notes”- Direct connections support password, key, certificate, SSH Agent, and keyboard-interactive prompts.
- ProxyJump hops work best with password, key, certificate, or SSH Agent auth.
- Explicit
KeyboardInteractiveauth over proxy chains remains limited today. - Imported
ProxyJumpchains from~/.ssh/configkeep their route structure when brought into OxideTerm.
SSH Config Import
Section titled “SSH Config Import”OxideTerm reads your existing ~/.ssh/config file and imports defined Host blocks as OxideTerm connections, preserving ProxyJump, User, IdentityFile, Port, and other directives.
Known Hosts & TOFU
Section titled “Known Hosts & TOFU”On first connection to a new host, OxideTerm uses Trust On First Use (TOFU):
- The host’s public key fingerprint is shown in a confirmation dialog.
- On acceptance, the key is appended to
~/.ssh/known_hostsusing OpenSSH-compatible semantics. - On subsequent connects, the stored fingerprint is verified automatically.
- Key-mismatch warnings are shown prominently — never silently ignored.
Saved Connections at Rest
Section titled “Saved Connections at Rest”OxideTerm encrypts saved connection metadata on disk instead of leaving it as plaintext JSON.
- Passwords / key passphrases / API keys stay in the OS keychain.
- Saved connection metadata is sealed locally with ChaCha20-Poly1305.
- Local config key lives in the OS keychain and unlocks the encrypted config document at startup.
- Legacy plaintext configs are migrated to encrypted storage on startup.
This means hosts, labels, auth metadata, jump routes, and related saved-connection state are protected at rest even before you export anything.
Encrypted Export / Import (.oxide)
Section titled “Encrypted Export / Import (.oxide)”Connection presets, including credentials, can be exported to a portable .oxide file for backup or transfer between machines.
| Property | Value |
|---|---|
| Cipher | ChaCha20-Poly1305 AEAD |
| KDF | Argon2id — 256 MB memory, 4 iterations, 1 thread |
| Integrity | SHA-256 checksum embedded in file header |
| Pre-flight | Validates memory availability before starting KDF |
| Key length | 256-bit derived key |
The .oxide format uses a passphrase you provide — OxideTerm never stores the passphrase. Import the file on any OxideTerm installation with the correct passphrase.
Session Manager
Section titled “Session Manager”Session Manager is the spreadsheet-style view of saved SSH connections. Open it from the sidebar or Command Palette (⌘K). It complements the saved-connection tree when you need to work across many profiles at once.
Connection Table
Section titled “Connection Table”The table shows all saved connections with sortable columns:
| Column | Description |
|---|---|
| Name | Connection display name |
| Host | Hostname or IP address |
| Port | SSH port, normally 22 |
| Username | Login username |
| Auth | Authentication type: password, key, or agent |
| Group | Group folder |
| Tags | Freeform tag labels |
| Last Used | Relative timestamp of the last connection |
| Actions | Connect, Edit, Duplicate, Delete |
Click a column header to sort. Hold Shift to multi-sort.
Search, Tags, and Groups
Section titled “Search, Tags, and Groups”The toolbar performs real-time fuzzy search across name, host, username, and tags. The folder tree filters by All Connections, Ungrouped, Recent, or a named group and its subgroups.
Tags are freeform labels for ad-hoc organization. Add or remove them from a row, see them as colored chips in the table, and include them in search. Typical tags include prod, staging, dev, datacenter-eu, and team-backend.
Use the folder tree to create subgroups, rename groups, or delete a group after moving its connections to Ungrouped. Drag rows into a group to reassign them.
Batch and Edit Actions
Section titled “Batch and Edit Actions”Select multiple connections with the row checkboxes. The toolbar exposes these bulk actions after selection:
| Batch Action | Description |
|---|---|
| Delete Selected | Remove multiple connections at once |
| Move to Group | Reassign multiple connections to a group |
| Add Tags | Apply tags to all selected connections |
Bulk operations ask for confirmation. The row Edit action opens the connection editor, where you can change connection properties, authentication method, key path, and group assignment. The toolbar also imports and exports encrypted .oxide files.
The Auto-Route action analyzes existing sessions to suggest an appropriate ProxyJump path for a new connection.
Active Sessions
Section titled “Active Sessions”The Active Sessions sidebar is a live view, not another saved-profile manager. It has two modes:
- Tree View — shows jump-host relationships with child nodes indented below parents.
- Focus View — shows a flat list of the currently active or connected sessions.
Node actions include connecting, disconnecting, opening a terminal, SFTP, IDE Mode, or port forwarding, drilling into the host, and saving a live connection as a preset.