SSH worktrees

Orca can drive agents on remote machines over SSH — useful for long-running builds, GPU boxes, or any environment where your laptop isn't the right place to run the work.

Add an SSH target

1. Open Settings → SSH.
2. Click Add Target. The host form opens in a modal (not inline under the list), so Host, Advanced, and Save stay reachable even with a long host list. Edit uses the same dialog and shows the target label plus user@host:port.
3. Fill in host, user, port, and optional identity file — or open the OpenSSH config picker in the same dialog to search ~/.ssh/config (including Included files), pick one host, and prefill the form. Hosts already saved in Orca show an In Orca badge. You can still import hosts in bulk from config when that flow is available.
4. If the key is passphrase-protected, Orca will prompt the first time.
5. Click Test to verify connectivity, then Save.

Dirty add/edit forms ignore outside clicks so an accidental click away does not discard your fields; use Escape, Cancel, or × to discard.

Use a target

When creating a worktree, choose an SSH target instead of Local. Orca will:

• Create the git worktree on the remote host.
• Run agents remotely through the SSH connection.
• Sync file events so the editor, diff, and browser still feel local.

Advanced connection options

Open Settings → SSH, edit a target, and expand Advanced Connection when the host needs a proxy, jump host, or SSH multiplexing override. Orca enables Reuse SSH connection for faster setup by default, which uses OpenSSH connection reuse on macOS and Linux so setup commands do not each pay a fresh SSH handshake. Turn it off only for hosts whose SSH policy rejects multiplexed sessions.

Passphrases

Passphrases are held in memory for the life of the Orca session. Closing Orca clears them. You can opt into a longer TTL under SSH settings.

Status

Remote worktrees show a chip with live SSH status — green connected, yellow reconnecting, red disconnected. While an SSH host is still connecting, Orca can list workspaces from persisted local metadata so the sidebar is not empty until the live provider comes up; those rows refresh to authoritative remote state once the connection settles. Disconnects don't kill running agents; Orca reconnects and re-attaches. When a host drops, the affected workspace card can show an inline Connect / reconnect control so you can recover without opening a terminal overlay or hunting the status bar. If an SSH relay drops with a "Multiplexer disposed" style failure, Orca recovers automatically instead of leaving the pane stuck until you restart. Agent status (working / idle / blocked) propagates over SSH the same way it does locally, so the sidebar and Agents feed reflect remote agents in real time.

Sessions across app close

Closing the desktop app no longer kills your remote PTY sessions. Remote terminal sessions are leased through the relay running on the remote host, so they survive Orca closing on your laptop. When you reopen the app and reconnect to the target, leased PTYs are restored to their tabs in the attached state, with their scrollback intact. A short grace period (5 minutes by default, configurable per target) gives the relay time to ride out a quick reconnect before tearing down detached sessions.

Downloading remote files and folders

Right-click in the SSH worktree file explorer:

• File → Download — native save dialog; copies the file to your laptop.
• Folder → Download Folder — recursive download into a folder you choose (desktop only).

Orca uses the same SSH transfer path as the connection. Folder download appears only when the connection advertises recursive folder transfer (typically full SFTP). Connections that stay on system OpenSSH-only transfer may still download files but not show Download Folder.

This is a desktop-only action — the web client doesn't expose Download because it relies on Electron's save dialog.

Open a remote workspace in VS Code

For SSH worktrees, the worktree menu's Open in list can hand the remote path to VS Code Remote-SSH when your configured app is VS Code or VS Code Insiders (code / code-insiders, or a direct path to those launchers).

1. Configure Settings → General → Open in menu so VS Code is listed (preset or custom command).
2. Right-click the SSH worktree (or use the worktree overflow menu) → Open in → VS Code.
3. Orca launches VS Code with Remote-SSH against that host and the worktree path (--remote ssh-remote+<host> <path>). The menu entry may show a Remote SSH badge.

Not supported for this remote path: Cursor, Zed, compound shell commands, or opening via a Remote Orca Server active runtime (those stay Local only). Use the Finder/Explorer item only for local paths.

Kerberos / GSSAPI

If a host in OpenSSH config sets GSSAPIAuthentication yes, Orca prefers the system OpenSSH transport for that target (the built-in ssh2 client does not speak GSSAPI). Keep a valid Kerberos ticket (kinit / your org's SSO) before connecting. Manual targets can also enable GSSAPI when configured for system SSH.

You do not flip a separate “Kerberos mode” switch for config-imported hosts — import/ssh -G carries the flag through.

FIDO2 / security keys

Hardware-backed OpenSSH identities (ed25519-sk, ecdsa-sk, including agent-backed security keys) also use system OpenSSH rather than the built-in ssh2 client. Orca detects the key type from your identity files and hands the connection to the OS OpenSSH binary so the touch / PIN prompt works as usual. Regular Ed25519, ECDSA, and RSA keys stay on the built-in transport. If OpenSSH is not available on the machine, those FIDO2 targets cannot authenticate until it is installed and on PATH (or in the usual Windows/macOS/Linux locations).

Linux hosts without a C/C++ toolchain

On first connect, Orca installs a small relay on the remote. Remote terminals need a native node-pty module. Linux packages often compile on the host; macOS/Windows relays use prebuilds.

If the remote is missing make, a C++ compiler, and python3, Orca still finishes connect for files, git, and the editor, but remote terminals will not work until build tools are installed. Example install hints Orca may surface:

• Debian/Ubuntu: sudo apt-get install -y build-essential python3
• Fedora/RHEL: sudo dnf install -y make gcc gcc-c++ python3
• Alpine: sudo apk add build-base python3
• Arch: sudo pacman -S --needed base-devel python

Install the tools, then reconnect so the relay can install native modules.

Port forwarding

For remote worktrees, the right sidebar shows a Ports tab (toggle with Cmd+Shift+I). Orca scans /proc/net/tcp on the remote and lists listening ports under Detected — one click forwards them to your laptop. You can also add forwards manually, edit them, or remove them. Forwards persist across app restarts and SSH reconnects, and privileged remote ports auto-remap locally (e.g. remote 80 → local 10080).