Making VMs, remote servers, and SSH workspaces first class in Orca

Executive Recommendation

The current destructive behavior comes from treating activeRuntimeEnvironmentId as a global app mode. That model does not satisfy concurrent remote work. It should become connection management and default selection, not the identity of the whole workbench.

Multiple app windows can be a later power-user feature, but should not be the first design. A window-per-host approach fights the existing single-renderer architecture and weakens the product goal of one client coordinating work across machines.

The product should feel configurable, not split into separate modes. A local-only user sees today's Orca. A remote-heavy user can choose All hosts to operate like a command center, or choose one host so the client feels almost entirely like that machine. Those are two views over the same host registry and session model.

Do not design around a minimal MVP boundary here. The intended destination is the full end-to-end model: concurrent local, SSH, VM-like, and paired-runtime hosts with safe host-owned routing. Implementation can still be phased for review and risk control, but the design should describe the complete product.

Vocabulary

What We Learned

Current behavior

• Desktop Settings are backed by the local Electron main process store.
• activeRuntimeEnvironmentId is stored as a local client setting, but it acts like a global workbench switch.
• Switching runtime environments currently resets runtime-scoped renderer state and can close remote terminals/browser pages.
• SSH already has partial multi-host shape: repos carry connectionId, SSH connection state is target-keyed, and remote workspace snapshots are keyed by target.
• The renderer still has one live WorkspaceSessionState, so runtime servers are not first-class concurrent peers yet.

Core product requirement

A user must be able to start work on one host, switch attention to another host, then come back without losing terminals, browser tabs, agent status, file context, or workspace ordering. Host focus is a viewing and default-target choice. It is not permission to close work on the old host.

Agent feedback

Product Model

Orca should present every machine or remote backend as a host. A host can be local, an SSH target, a paired Orca runtime server, or a VM profile backed by either SSH or runtime RPC.

"VM" should remain a user-facing label, not a required separate transport in v1. Today a VM can be an SSH target or a remote runtime server. Later, if Orca offers managed cloud machines as a revenue source, those machines should slot into the same host model instead of creating a parallel workspace concept.

Sidebar behavior

• Group workspaces by host in the sidebar.
• Each host header shows label, health, reconnect state, and active agent count.
• Users choose visible hosts with a searchable multi-select menu modeled after the existing Projects selector: sticky All hosts, search, checked rows, and status metadata.
• Selecting one visible host is the focused-host experience. Selecting multiple hosts is a custom command-center view. Neither mode disconnects hidden hosts.
• New workspace defaults to the focused host, but existing workspaces keep their host.
• Searching and Cmd+J should work across hosts, with host labels visible in results.
• Hide the host visibility UI entirely when there are no remote hosts. Local-only users should keep today's sidebar.

Host actions

• Manage Host: open a host details panel.
• Reconnect / Disconnect: connection lifecycle only.
• Rename: local display label.
• Remove: forget the host and clean up host-scoped local state safely.
• Open in New Window: optional later feature, not MVP.

Two Valid User Modes

Primary user journeys

Sidebar Mock

Hosts should behave as a visibility filter above the existing organization controls. The existing Group by, Sort by, filters, and project filter still apply inside the visible host set.

How this maps to the real sidebar

• Add Hosts above the current Group by control in SidebarWorkspaceOptionsMenu, but only when at least one non-local host exists. Use the same searchable multi-select popover pattern as the existing Projects selector.
• Keep Group by as None / Status / PR / Project; do not add Host there because users still need status/project grouping inside a host.
• Add a compact host summary strip below the Workspaces header when more than one host exists. Hide it for local-only users.
• In All hosts, render host headers above the existing grouped workspace rows. When one or more specific hosts are selected, hide unchecked host sections without disconnecting them.
• Host header menus own connection actions: manage, reconnect, disconnect, rename, remove, and later open in a separate window.

Settings Model

Host Details surface

Do not build a second giant Settings app. Add a focused Host Details panel reachable from each host header and from Settings > Servers.

• Overview: status, latency/health, server version, protocol compatibility.
• Connection: SSH/runtime endpoint, credentials, reconnect policy.
• Agents: detected Codex/Claude/Cursor/Gemini/OpenCode on that host.
• Terminal: default shell and host-specific terminal capabilities.
• Storage: default workspace/clone directory, disk/port/resource status.
• Danger zone: disconnect, remove, clear cached host session.

Effective settings rule

For ambiguous preferences, use inheritance: effective = host override ?? client default. Show when a host is overriding the client default, and provide a clear reset action.

In the settings navigation, keep client settings as the default top-level destination. Add a Servers / Hosts area for saved local, SSH, runtime, and VM hosts. From the sidebar, Manage Host should deep-link directly to the selected host details, not change the meaning of the entire Settings page.

For settings that can vary by host, a scoped selector is enough: a dropdown such as Apply to: Client default / Local Mac / Windows VM / Linux Builder. This is similar to Windows settings surfaces that let users choose whether a setting applies to Windows or WSL. The key rule is that the selected settings scope must be visible in the control itself, not inferred from sidebar focus.

How SSH Fits

SSH already has many of the properties this design needs: target-keyed connection state, repo-level connectionId, per-target remote workspace snapshots, SSH-aware PTY IDs, remote file operations, and port forwarding. The new model should give those pieces a clearer product wrapper rather than replacing them.

Host identity

Conceptually, host IDs should look like this:

• local
• ssh:<targetId>
• runtime:<environmentId>

An SSH connection is both a saved connection profile and an execution host. The connection profile stores how to reach the machine. The execution host identity is what repos, worktrees, PTYs, agents, browser sessions, and file operations route through.

A VM is not a special case here. A Windows VM reached over SSH is ssh:<targetId>. A cloud VM running a paired Orca runtime is runtime:<environmentId>. A future Orca-managed VM should still expose a host ID and adapter rather than leaking cloud-provider details into workspace routing.

SSH lifecycle

SSH in the sidebar

A saved SSH target appears as a host section, not merely as a small badge on a project. The transport can still be visible in secondary text:

• Windows VM · SSH · Connected · 2 agents
• Linux Builder · SSH · Reconnecting
• Remote QA Box · SSH · Needs passphrase

Host Details for SSH

• Connection label, hostname, username, port, and auth method.
• Reconnect status, last error, passphrase/password prompts.
• Remote default clone/workspace directory.
• Detected shells, installed coding agents, and terminal capabilities.
• Remote ports, relay capability, server/relay version, and health.
• Danger actions: disconnect, remove host, clear cached sessions.

Keep adapters distinct

The UI and routing language should converge, but the implementation should not force SSH and paired runtime servers into one transport too early. Use an adapter shape:

• { kind: 'local' }
• { kind: 'ssh', targetId }
• { kind: 'runtime', environmentId }

Features ask "which host owns this worktree?" and dispatch through the right adapter. That preserves SSH-specific filesystem, PTY, relay, and port-forward behavior while making the product feel coherent.

SSH-specific risks

• Passphrase-protected targets may be deferred; do not hide their restored workspaces.
• Windows SSH hosts use different path and shell semantics; never assume local POSIX paths.
• Relay capabilities may differ by version; Host Details should surface unsupported features.
• Remote PTY session IDs must remain connection-scoped so reconnects do not attach the wrong host.
• SSH targets may not run the same Orca relay or agent versions as local; gate features by capability.

Architecture Direction

Introduce execution host identity

Add a normalized host/routing key that can represent local, SSH, runtime, and future VM hosts.

• local
• ssh:<targetId>
• runtime:<environmentId>

Bind work to hosts

• Repos carry host identity.
• Worktrees derive host identity from repo.
• Terminal/browser/editor operations route by worktree host, not by global app mode.
• New workspace creation uses focused/default host only as an initial value.

Data ownership rules

Source of truth rules

• The local client owns the list of known hosts, display labels, sidebar scope, and UI preferences.
• The owning host owns execution facts: filesystem, shell, git state, running terminals, live browser sessions, ports, and installed agents.
• Repo/worktree records must include enough host identity to route without consulting the current sidebar scope.
• Cached remote snapshots are client-side projections of host-owned state. They can render offline UI, but they are not permission to mutate remote state while disconnected.

Partition session state

Move from one global session blob toward host-partitioned session slices. The renderer can still render one unified workbench, but persistence and routing should be host-aware.

• workspaceSessionsByHost.local
• workspaceSessionsByHost.ssh:windows-vm
• workspaceSessionsByHost.runtime:prod-builder

Terminal and session identity direction

Existing SSH PTY IDs already point toward the right model: src/shared/ssh-pty-id.ts embeds the SSH connection ID into app-visible PTY IDs so relay-local IDs cannot collide after restore. Runtime and local sessions should converge on the same principle.

• Prefer structured ownership at API boundaries: { hostId, sessionId } for new code and persisted records.
• Keep string wrappers for compatibility where existing tab/layout maps require string keys, but make them parseable and host-scoped.
• Do not let cleanup paths infer runtime ownership from getActiveRuntimeTarget(get().settings). A terminal stop/kill must use the owner host of the worktree, tab, or PTY being closed.
• Audit maps such as ptyIdsByTabId, terminalLayoutsByTabId, browser page maps, and tab order maps for assumptions that IDs are globally unique.

Stop using global active runtime for mutations

activeRuntimeEnvironmentId should not decide where a terminal, file operation, git action, browser page, or agent launch goes. The owning worktree should decide.

Compatibility bridge

During migration, keep a compatibility layer where activeRuntimeEnvironmentId can still provide a default host for legacy flows. New code should ask for host identity from the repo/worktree/tab owner first, then fall back to the focused/default host only for creation flows.

Existing remote-server users should not experience a jarring migration. Their current active runtime becomes the focused/default host. The main visible change is additive: they may now also see local-machine workspaces when using All hosts, and can narrow back to the remote server by selecting only that host.

Version skew and capability gating

Multi-host Orca must assume hosts can run different Orca builds. A new desktop client may connect to an old runtime server, an old desktop client may connect to a newer server, and two remote hosts may expose different feature sets at the same time.

The current runtime compatibility foundation is already the right shape: src/shared/protocol-version.ts declares protocol versions and capabilities, src/shared/protocol-compat.ts evaluates whether client/server protocol ranges overlap, and runtime.status.get returns optional protocol and capability fields. The host model should promote that from a hidden preflight into visible per-host state.

The important rule is that Orca app versions are diagnostic labels, not the compatibility contract. A desktop client at app version 1.8.0 should be allowed to use a server at app version 1.7.2 if their runtime protocol ranges overlap. Exact app version equality would make remote hosts unnecessarily brittle, especially for SSH boxes, long-lived VMs, and future cloud-hosted machines that may update on a different cadence from the user's laptop.

Compatibility should be modeled as host state, not app state. Each host registry entry needs a verdict such as compatible, server-too-old, client-too-old, unknown, or degraded, plus the capabilities that were actually advertised by that host. The sidebar, Settings, worktree actions, terminal launch, browser actions, hosted review polling, and background agents should all ask the owning host for this verdict before mutating anything.

Handshake model

1. When a host connects, call its cheapest status endpoint first, such as runtime.status.get for runtime servers or the SSH relay status equivalent for SSH hosts.
2. Record appVersion, runtimeProtocolVersion, minCompatibleRuntimeClientVersion, capabilities, platform, relay version, health, and last successful check time on the host registry entry.
3. Evaluate protocol compatibility per host. A host is hard-blocked only when the client is below the server's minimum client protocol, or the server is below the client's minimum server protocol.
4. Evaluate optional features from capabilities. Missing capabilities disable only the specific feature, not the whole host.
5. Cache the verdict per host and re-check on reconnect, explicit refresh, server update, relay reinstall, or status-version change.

• Never require exact app-version equality between client and server.
• Use protocol range overlap for hard allow/block decisions.
• Use capabilities for additive feature availability.
• Treat missing protocol fields as protocol 0 so pre-contract servers produce a clear update-server path instead of mysterious runtime failures.
• Prefer read-only cached visibility for incompatible hosts. Users should still understand that the host exists and why it is unavailable.
• Cache compatibility per host, not globally, and invalidate it on reconnect, server update, or status version change.
• Host Details should expose app version, protocol version, minimum compatible peer version, and capabilities for debugging.

Operational contract for mismatched versions

The client should treat every remote host as an independent compatibility island. A new client connected to an old server, an old client connected to a new server, and a fully current local host can all coexist in the same sidebar. Compatibility must be checked at the host boundary before the host is allowed to receive mutating commands.

1. Status-only bootstrap: the first call to a remote host must be a backwards-compatible status handshake. It should not depend on the full runtime API being compatible. If even the status endpoint is unavailable, classify the host as unknown or needs update and keep cached read-only state visible.
2. Hard compatibility verdict: compare the client's protocol range with the host's reported protocol range. If they do not overlap, the host remains visible but disabled for terminals, agents, git writes, file writes, browser actions, and settings mutations.
3. Soft capability verdict: if the protocol range is compatible, use the host's advertised capabilities to enable or disable individual features. This is how a new desktop client can safely work with an older but still compatible server.
4. Per-command guard: every host-owned mutation should check the host compatibility/capability verdict at dispatch time, not only when rendering the button. UI hiding prevents confusion; dispatch guards prevent stale UI or background workflows from writing to an incompatible host.
5. Update direction: when blocked, the host registry should preserve a reason code such as server-too-old, client-too-old, or missing-capability. The sidebar badge and Host Details page can then say exactly whether the user should update the desktop client, update/reinstall the remote server or relay, or simply accept that one optional feature is unavailable on that host.
6. Owner-scoped fallback: if an older server cannot answer a newer API, the client may fall back only for the host that owns the request, and only to a known compatible older endpoint. It must not silently reroute the request to the focused host or to the local machine.

Implementation inventory to start from

Phased Plan

Risks

• ID collisions: repo, worktree, tab, browser, and PTY IDs from many hosts may coexist. IDs must be namespaced or validated by host.
• Routing mistakes: file, git, terminal, browser, and agent operations must route from worktree ownership, not a global active setting.
• Session corruption: mixed-host state in one session blob can overwrite or mis-hydrate remote work.
• Protocol skew: different hosts may run different Orca versions and capabilities. Compatibility and feature availability must be evaluated per host.
• Security boundaries: auth/account settings and command execution must not leak between hosts.
• Resource use: many live hosts means many terminals, browser pages, and subscriptions. Do not optimize this first, but leave room for later throttling, sleep, and resource-budget policies.
• UX ambiguity: users must always know which host owns a workspace and which settings scope they are editing.

Immediate Follow-ups

1. Write a design doc for ExecutionHostId, host registry, session partitioning, and migration.
2. Audit every activeRuntimeEnvironmentId read and classify it as default host, owner host, or client setting.
3. Prototype a host-grouped sidebar with local plus one remote server.
4. Add a Host Details panel for saved servers without duplicating the full Settings page.
5. Preserve remote terminals when changing focus between local and remote contexts.
6. Fix the terminal-read bug where Claude Code's visible full-screen TUI output can appear as blank lines through orca terminal read.
7. Add operator safeguards: do not close live agent terminals solely because transcript output is quiet or blank.

Acceptance Criteria

• A local-only user with no saved remote hosts sees no host visibility strip and no extra sidebar complexity.
• A user can connect Local Mac plus at least one SSH or runtime host and see both in one sidebar under All hosts.
• Selecting one host, multiple hosts, or sticky All hosts changes visible workspaces and creation defaults without closing terminals, browser pages, or agents on other hosts.
• Settings always makes the edited scope visible: client, host, or repo/worktree.
• SSH targets with expired auth or offline status still show restored workspaces and a clear reconnect path.
• A host with an incompatible server version is visible but blocked from unsafe mutations, with clear update guidance in the host header and Host Details.
• Optional features are enabled per host based on capabilities; one older host does not disable newer features on another host.
• File, git, terminal, browser, and agent actions route by the workspace owner host, not by the current visible host filter.
• Removing or disconnecting a host is the only path that intentionally tears down that host's live remote resources.

Agent Implementation Notes

A future agent picking this up should treat this as a multi-step architecture change, not a sidebar-only feature. The UI can ship incrementally, but the safety boundary is routing.

• Start with a call-site inventory for activeRuntimeEnvironmentId, getActiveRuntimeTarget, connectionId, and runtime/SSH PTY ID helpers.
• Classify each call site as: client setting, creation default, owner-host mutation, status display, cache key, or compatibility fallback.
• Add tests before broad rewrites. Regressions here can destroy terminals or route writes to the wrong machine.
• Preserve SSH behavior while making it more visible. Do not regress passphrase-deferred reconnects, Windows remote paths, or remote port forwarding.
• Avoid destructive switching in prototypes. A host focus change should never call close on old host terminals unless explicitly testing disconnect/remove behavior.
• If UI changes are made, verify local-only users still see the current simple sidebar with no host-scope chrome.

Resolved Decisions and Remaining Unknowns

Resolved decisions

• VM is a loose host label, usually backed by SSH or paired runtime.
• The design target is full end-to-end implementation, not an intentionally narrow MVP.
• In All hosts, new workspace creation should use the focused/default host but make the target host visible and changeable.
• Host-varying settings can use a visible host dropdown rather than a duplicate Settings app.
• The desktop client owns paired runtime server configuration.
• Existing active-runtime users migrate to a focused/default host and can still narrow the app back to that server.
• Background host resource policy can wait, as long as routing and teardown semantics leave room for future throttling.

Remaining unknowns

• Exact read-only behavior for offline hosts: recommended default is show cached sidebar, tabs, terminal history, and metadata; disable filesystem/git/terminal mutations until reconnect; allow local-only metadata edits such as rename/remove.
• Exact shape of the host-scoped session ID migration: structured { hostId, sessionId } should be the destination, with parseable string wrappers where legacy maps require string keys.
• Which status signals define "quiet but alive" for agent terminals?
• How future Orca-managed cloud hosts are provisioned, billed, and surfaced. They should still conform to the same host registry and execution-owner model.