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.

SSH remote workspace — agents run on the remote host, the editor and diff stay local

Add an SSH target

Open Settings → SSH.
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.
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.
If the key is passphrase-protected, Orca will prompt the first time.
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.

Host key verification

Orca checks built-in SSH connections against your effective OpenSSH known_hosts files and keys it previously saved. Existing matches connect silently. With the default policy, Orca accepts and remembers a host on first contact and shows its fingerprint; StrictHostKeyChecking yes rejects unknown hosts, while no / off accepts without saving a trust record.

A changed, revoked, or unexpectedly different key type is rejected before Orca asks for a password or key passphrase. If you intentionally rebuilt or reprovisioned the host, verify its new fingerprint first, then follow the recovery path in the error. For a known_hosts mismatch, Orca provides the appropriate ssh-keygen -R command (including the bracketed host and port when needed).

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.

Hosts that ask for a verification code or another keyboard-interactive prompt (a one-time password, an MFA challenge, or a similar prompt) work over the built-in connection: Orca relays the prompt to you and forwards your answer. If the prompt is part of a scripted setup step, it is deferred to a step you can answer rather than failing the connect.

If the built-in client and host have no compatible SSH algorithm, Orca retries through your system ssh, which can use the algorithms configured for that installation.

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, replaying scrolling output and restoring full-screen app panes from their rendered frame instead of returning them blank or fragmented. Keystrokes you type while a restored SSH terminal reattaches are kept, not dropped. 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 connection 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. They live on the host's managed Orca server, so they survive Orca closing on your laptop. When you reopen the app and reconnect to the target, the sessions are restored to their tabs in the attached state, with their scrollback intact. A structured chat on a managed server keeps its provider loaded while a reply is running or a question is waiting, so an approval is still there after the desktop disconnects. Losing contact with a host is not evidence that its work stopped, so check the host before starting a second agent on the same worktree.

Reconnect and restart

Open files, live agent tabs, and paused Claude or Codex resume offers survive an SSH reconnect and an app restart, so the workspace comes back the way you left it. Keys you type while the connection is down are delivered exactly once and in order when it returns, and a pane's scrollback and size survive the reconnect. Open tabs reattach after a managed server update. Tabs you closed long ago no longer return as empty shells, and clicking an SSH worktree whose last tab you closed opens a fresh terminal.

To leave an on-demand SSH host disconnected when Orca starts, edit that host and turn off Advanced → Reconnect on launch. The switch is on by default. While it is off, Orca waits until you select Connect before reconnecting the host or its managed server for that session.

Shell startup files that print text, folders with tens of thousands of entries, and 64-bit ARM Linux servers no longer break or drop the connection. When two machines share a path, files, browser tabs, links, and drag-and-drop stay on the machine they belong to.

The orca CLI on an SSH host

By default, orca commands run on an SSH host reach only that host's own terminals and orchestration messages. An agent there can still report back to a coordinator that dispatched it, but it can't reach your other hosts, desktop control, accounts, or settings. To let that host's agents create worktrees, open terminals, or dispatch work through orca, turn on Allow this host's orca CLI to control Orca for that host (Settings → SSH → edit the host → Advanced Connection). Terminals carried over from v1.4.224 do not have orca; run orca commands in a new terminal on the same host.

When deleting an SSH workspace that Orca cannot delete on the host, Remove from Orca removes it from the app and leaves its files on the host.

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).

Configure Settings → General → Open in menu so VS Code is listed (preset or custom command).
Right-click the SSH worktree (or use the worktree overflow menu) → Open in → VS Code.
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).

Managed Orca server

On first connect, Orca sets up its own server on the host — a pinned runtime it ships and keeps up to date — so a connection no longer fails because the host has the wrong Node version or no build tools. There is no setting to turn this on.

If neither your computer nor the host can download the Node.js runtime, the connection error offers Use a Node.js mirror…. Review or replace the prefilled mirror, then choose Save and retry; Orca verifies each download against its pinned checksum. If the configured mirror also fails, open Settings → Advanced → Network to correct the mirror before reconnecting.

An empty host is set up and connects to its managed server.
A host that already has Orca projects but no open terminals moves its projects, folders, project groups, and open editor tabs onto the managed server on its next connect.
Terminals left running by v1.4.224 keep working in their existing tabs through the upgrade and reconnect; new terminals on that host open on the managed server.
A host the managed server cannot run on no longer falls back to the old SSH runtime. The connect fails with the reason, and Settings → SSH Hosts shows it — use an older Orca version to keep connecting to that host.

Manage each server under Settings → Managed servers: see its version and running terminals, Update or Roll back, Recover an interrupted update, or Stop… / Forget… it. If terminals are running, Update anyway updates the server without closing them. The CLI mirrors those actions — orca environment status|update|rollback|recover|stop|forget — see the CLI reference.

Runtime choices

The old per-host Runtime selector (Auto / Orca-managed Node / Host Node) and the relay-only lifecycle settings are gone: every SSH connection runs on the managed Orca server. If Orca cannot run the managed server on a host — an unsupported OS or CPU, a noexec home directory, or an SSH server that refuses port forwarding — the connect explains why in Settings → SSH Hosts instead of silently falling back.

Port forwarding

For remote worktrees, the right sidebar shows a Ports tab (toggle with Cmd+Shift+I). Orca scans the workspace's own host — the managed SSH server or paired server the worktree runs on, not your laptop — and lists listening ports under Detected; one click forwards them to you, and you can stop a detected port from the same panel. You can also add forwards manually, edit them, or remove them. Saved forwards return on managed hosts after a reconnect, persist across app restarts, and privileged remote ports auto-remap locally (e.g. remote 80 → local 10080). If a saved forward cannot start, its row explains why and lets you remove it.