SSH

vord can start a terminal session directly on a remote host over SSH, right next to your local claude, codex, and shell sessions. Connections live in Settings → Workspace → SSH, and once saved, you launch them from the command palette (⌘K), the Session menu, or an optional toolbar button you add via Customize Toolbar….

Saved connections (global or per project)

A saved connection is a named SSH target — host, user, port, and an auth method — that you can start with one click instead of typing ssh user@host every time.

1. Open Settings → Workspace → SSH → Connections and click Add connection.
2. Enter a name (optional — vord falls back to user@host if you leave it blank), the host, user, and port (default 22).
3. Pick an auth method:
   • SSH agent (default) — uses whatever identities your ssh-agent already has loaded.
   • Private key — pick a key file with the file picker.
   • Password — typed or pasted at connect time and stored in the Keychain (see the password chip below).
4. Pick a scope: Global (visible in every project) or a specific project.
5. Optionally expand Advanced for legacy server compatibility (older KEX/cipher algorithms) and extra ssh flags (space-separated).
6. Save. The connection now shows up in the SSH toolbar pool and in the command palette.

Click the connection from either place to start an .ssh session in the matching project context immediately.

Caution

Host and user can’t be empty or start with -. This blocks argv injection — ssh has no -- terminator, so a value like -oProxyCommand=… could otherwise run an arbitrary command. The save button stays disabled until the fields are valid.

Passwords and key passphrases are never stored in the connection file itself — only in the system Keychain, under vord’s own service namespace. See Settings Reference for where the non-secret connection data lives.

Reading ~/.ssh/config (read-only)

vord also reads your local ~/.ssh/config live and lists its host aliases next to your saved connections, under From ~/.ssh/config in Settings → Workspace → SSH.

These entries are start-only — vord never writes to that file. User, port, and key selection are whatever your config file already says; vord only appends its own global -o options on top (see below).

Note

Wildcard aliases (*, ?, a leading !), and aliases starting with -, are skipped while parsing — they aren’t concrete hosts, or they’d be an injection risk. Match blocks and Include lines are ignored entirely.

Global options

Two switches in Settings → Workspace → SSH → Global options apply to every SSH connection you start, whether it’s a saved connection or a ~/.ssh/config alias:

Option	Default	Effect
Keep connections alive	On	Sends a keep-alive every 30 seconds so idle SSH sessions stay open.
Accept new host keys automatically	On	Trusts an unknown host on first connect instead of prompting (StrictHostKeyChecking=accept-new).

The SSH toolbar pool and ⌘K

Once you have at least one saved connection or config alias, a network icon with a count can appear in the cockpit toolbar. It isn’t on the toolbar by default — add it through the toolbar’s Customize Toolbar… command, or use Session → Open SSH connection. Click it (or the menu item, or ⌘K) to get a filterable list (type to search) of everything you can connect to — saved connections and config-file hosts together. The same list is reachable through the command palette (⌘K).

Either path starts a fresh .ssh session. For how session starting, resuming, and the claude/codex/shell/SSH picker work in general, see Starting Sessions.

The password / passphrase / sudo chip

If a session prompts for a password interactively — an SSH login password, a key passphrase, or a sudo prompt inside the remote shell — vord recognizes the prompt at the end of the last terminal line and shows a small chip in the bottom-right corner of that session’s terminal.

Click the chip to insert the saved password (raw text plus Enter). It’s never sent automatically — inserting is always a deliberate click.

Note

This only works for saved connections that have a password stored in the Keychain (checked once at session start). Config-alias sessions without a matching saved connection get no chip. If the Keychain read fails or no password is saved, the chip shows a short error state instead of silently doing nothing — and the password never touches the transcript, logs, argv, or environment.

Detection is a pure output heuristic: it matches known prompt suffixes (password:, '…':, [sudo] password for …:) at the end of a line. vord has no access to the terminal’s echo state, so this can’t be made more precise than string matching.

Installing a key with ssh-copy-id

If you’re currently using password auth, the Install key action on a connection row converts it to key-based auth for good: it copies your public key to the target server.

1. In Settings → Workspace → SSH → Connections, find the connection and click Install key.
2. vord opens a fresh, plain shell session in the matching project and types the ssh-copy-id command for you (including -i <key> / -p <port> where relevant).
3. The server asks for the password once, interactively — type it in the terminal as normal.

This runs in a separate shell session, not inside the .ssh session itself — it’s a one-off local helper command, not something vord manages afterward.

File transfer with scp (drag-drop upload, fetch download)

Upload: drag one or more files from Finder onto an .ssh tile in the cockpit. vord uploads them via scp into the home directory of the remote host.

Download: right-click an .ssh session and choose Fetch file from host…, then enter the remote path. The file lands in ~/Downloads.

Caution

File transfer needs a saved connection with key or agent authentication. Password-only connections can’t use it — scp runs unattended with BatchMode=yes, so it has no way to answer an interactive password prompt. vord tells you this directly (“file transfer needs key authentication”) instead of trying and failing silently. Config-alias sessions without a saved connection have no transfer path at all.

Transfers run as a separate background process, not inside the session’s terminal — you get a short notification and an event-log entry, not a progress bar. There’s no timeout, so a large transfer can run as long as it needs.

The SSH host badge

An .ssh tile and its focus view show a small pill with the connection name (or config alias) next to the other status badges — so you can tell at a glance that a session is running remote, not local. It’s purely informational.

Security (argv-injection guard, passwords in Keychain only)

A few security properties hold across the whole SSH feature, not just individual actions:

• No argv injection. Host, user, and ~/.ssh/config aliases that start with - are rejected or skipped wherever vord builds a command line for them — a value like -oProxyCommand=… can’t smuggle an extra flag into ssh, scp, or ssh-copy-id.
• Passwords never live in plain settings. Saved connections persist to a secret-free JSON file; passwords and key passphrases exist only in the system Keychain.
• Passwords stay out of logs. The password chip inserts text directly into the terminal — it’s never written to the transcript, event log, process argv, or environment variables.

SSH sessions go through the same license gate as any other session start (Basic/Pro/Trial/Perpetual) — see Settings Reference for licensing details, and Sending Input for paste and snippet behavior that applies to SSH sessions too.