Remote connectivity and execution
Orca lets desktop, mobile, and command-line clients work with services, files, terminals, agents, and workspaces on another machine. Pairing identifies trusted Orca runtimes. SSH gives direct access to a host and can also carry a managed Orcad service. The selected execution host stays with each request so remote work does not silently run on the local computer.
Connectivity model
The connectivity model separates the user interface from the machine that owns the work. A local host runs on this computer. A paired runtime runs Orca services in another environment. An SSH host gives direct access to that environment or carries a managed Orcad service for it.
Execution hosts
An execution host is the machine that owns a path, workspace, terminal, or service and performs the related action. Orca gives each host a stable ID so equal path names and repository IDs on different machines do not share ownership.
| Host kind | ID form | Main use |
|---|---|---|
| Local | local | Files, shells, and services on this computer |
| Paired runtime | runtime:<environment> | Orca calls, remote sessions, and host-owned workspace state |
| SSH host | ssh:<target> | Commands, files, terminals, and network access through SSH |
An SSH host and its managed Orcad service can represent one physical machine. Orca keeps their internal IDs for routing but shows one machine in the host picker.
References: src/…/execution-host.ts• L5-24 src/…/managed-orcad-execution-host.ts• L35-79
Access paths
Orca chooses an access path from the requested host and the work that path must support. A paired runtime uses its verified runtime connection. Direct SSH uses the SSH target. A managed service uses SSH to reach the host and a tunnel to reach Orcad on that host.
This diagram shows the main routes from a client to remote work.
flowchart LR
C[Desktop, phone, or CLI] -->|Pairing| R[Paired Orca runtime]
C -->|SSH| H[SSH host]
H -->|Managed setup or existing service| O[Managed Orcad service]
O -->|Tunnel| R
The route does not change the owner of the work. The remote host remains responsible for its files, sessions, processes, credentials, and service state.
References: src/…/runtime-environment-transport-routing.ts• L33-145 src/…/ssh-host-server-on-connect.ts• L119-193 src/…/mobile-desktop-relay.ts• L51-61
Pairing and runtime connections
Pairing creates a saved link to another Orca runtime. The desktop and CLI verify the pairing and remote identity before they use the saved environment. A mobile-only pairing code cannot be reused as a general client link; the CLI rejects it before contacting the host. The Pairing and device trust page explains trust exchange and device records. The Remote runtime transport page explains request and stream transport.
Runtime lifecycle
The runtime lifecycle covers adding, verifying, connecting, reconnecting, disconnecting, and removing an environment. Adding a CLI environment can save an unreachable code for later, but a reachable host that refuses the code is reported at once. A manual disconnect pauses automatic use. An explicit connect clears that pause and checks the environment again. Removing an environment also retires its transport state and host-owned session references.
For a managed SSH environment, a runtime connect restores the service behind SSH. For a WSL environment, the local WSL host service is made ready through its host bridge. A failed or refused setup remains visible as an unavailable or blocked host instead of becoming local work.
References: src/…/environment-pairing-exchange.ts• L10-69 src/…/environment-pairing-exchange.test.ts• L5-17 src/…/runtime-environment-connectivity-handlers.ts• L84-177 src/…/runtime-environment-managed-tunnel.ts• L35-53 src/…/ssh-host-server-on-connect.ts• L120-195
Runtime request routing
Runtime calls use one-shot requests for startup and recovery. Frequent actions use reusable connections. Shared control serves supported calls. Subscriptions carry long-lived updates. The client checks the saved pairing revision and runtime identity before sending work, which prevents a request for an older peer from reaching a replacement.
This diagram shows how a call reaches the selected runtime.
flowchart TD
A[Client request] --> B[Resolve environment]
B --> C[Check pairing and runtime identity]
C --> D{Supported route}
D -->|Shared control| E[Reusable control connection]
D -->|Cached request| F[Reusable request connection]
D -->|Recovery or unsupported| G[One-shot request]
E --> H[Reply or stream]
F --> H
G --> H
Subscriptions use the same support check. If a runtime loses a capability or changes identity, Orca refreshes the environment and does not reuse stale evidence.
References: src/…/runtime-environment-transport-routing.ts• L61-145 src/…/runtime-environment-support-routing.ts• L54-77 src/…/runtime-environment-revision-guard.ts• L4-35
Runtime server exposure
The runtime has a local transport for its own clients and can expose a WebSocket transport for paired clients. It binds to loopback by default. It widens exposure only for an explicit network need or a connected network pairing. Pairing identity, device tokens, and end-to-end encryption protect the network path.
The server publishes its live endpoint only after the transport is ready. It also bounds heartbeats, payloads, and client connections so a dead or excessive client cannot hold the runtime open.
References: src/…/runtime-rpc-lifecycle.ts• L32-212 src/…/ws-transport.ts• L18-28 src/…/ws-transport.ts• L142-226
Mobile client relay
A paired phone can ask the desktop to reach a configured runtime. The desktop exposes its last-known host catalog, opens an encrypted runtime link for the phone and selected environment, and forwards only methods marked for the execution host. Methods that belong to the paired desktop stay on the desktop.
Relay access can require the desktop to sign in to Orca, while a LAN path does not require an account. The relay keeps active and pending paths separate during recovery. It uses named outcomes for host-offline, credential, and transport states instead of treating an unnamed socket close as proof of a desktop state.
References: src/…/runtime-rpc-websocket-dispatch.ts• L34-180 src/…/mobile-relay-host-catalog.ts• L31-97 src/…/mobile-relay-host-descriptions.ts• L20-65 src/…/MobileRelaySignInPanel.tsx• L5-45 mobile/…/host-status-gates.ts• L11-179 mobile/…/relay-host-reachability.ts• L5-31
SSH execution
SSH provides direct access to a remote machine for commands, files, terminals, and port forwards. Orca resolves the user's OpenSSH rules first, checks the host identity at connection time, and shares the resulting connection with higher-level actions.
SSH target resolution
An SSH target can be a saved host or an OpenSSH alias. Orca uses OpenSSH's resolved view for the effective host, port, user, proxy, jump host, identity files, and host-key settings. This makes the target follow the user's real SSH route rather than a partial copy of it.
The host picker and importer accept concrete aliases that still exist when they are resolved. Unreadable or uncertain included configuration stays strict when it may contain host-key policy. Two aliases that resolve to the same route are treated as one host view. Each target has a generation so a replacement target cannot inherit channels, forwards, or workspace work from an older target with the same label.
References: src/…/ssh-g-config-resolution.ts• L44-105 src/…/ssh-g-config-resolution.test.ts• L39-165 src/…/ssh-config-host-picker.ts• L26-123 src/…/ssh-target-id-migration.ts• L9-160 src/…/AddRemoteHostSshConfigPicker.tsx• L15-76
SSH trust and sign-in
The SSH host key is the server identity used to detect a changed or impersonated host. Orca reads the user's known-hosts sources and keeps its own accepted-key records without changing shared OpenSSH files. A changed or unidentifiable key stops the connection before credential fallback.
Sign-in can use an agent, configured keys, passwords, or keyboard-interactive prompts. A remembered password may answer one reconnect challenge. A repeated password challenge causes a new prompt. One-time codes always require a fresh answer. A user cancellation blocks background sign-in until an explicit connect asks again.
References: src/…/ssh-g-config-resolution.ts• L9-32 src/…/ssh-auth-resolution.ts• L71-243 src/…/ssh-connection-manager-sign-in-reuse.test.ts• L63-197 src/…/ssh-connection.test.ts• L170-479 src/…/ssh2-host-key-verification.ts• L38-178 src/…/ssh-passphrase.ts• L11-66
SSH connection continuity
The connection manager keeps one active connection per target and protects replacement attempts from late results. It does not reconnect a target after an explicit user disconnect. Accepted sign-in data may survive an automatic replacement when the effective route is unchanged.
Short network interruptions and a host waking from sleep can recover through a fresh retry budget. Wake and unlock events also probe managed tunnels because keepalive may not detect a lost route. A replacement connection remains authoritative when an older handshake or system-SSH process finishes late.
References: src/…/ssh-connection-manager.ts• L19-177 src/…/ssh-connection-wake-retry.test.ts• L86-194 src/…/ssh-connection-loopback-cancel.test.ts• L56-98 src/…/ssh-host-sleep-reconnect.ts• L9-39 src/…/ssh-connection-state-callbacks.ts• L20-45
Remote commands and files
Remote commands run through bounded SSH channels and remote files use the same host connection. File uploads validate local sources, reject path escapes and unsafe entries, limit concurrent work, and stop when the session or caller closes.
The result stays separate from transport failure. If a channel closes before Orca knows the final remote state, it reports an unknown result instead of claiming success or inviting a duplicate command. POSIX and Windows hosts use their own path and command rules. System SSH keeps local archive failures separate from remote command failures.
References: src/…/ssh-exec-rc-stdout-noise.test.ts• L45-56 src/…/sftp-upload.ts• L1-132 src/…/sftp-upload.test.ts• L35-131 src/…/sftp-upload-pipeline.test.ts• L141-229 src/…/ssh-connection-sftp-wire.test.ts• L306-353 src/…/system-ssh-file-transfer.ts• L48-167 src/…/system-ssh-operation-lifecycle.ts• L6-179
Network forwarding
Port forwarding makes a service on the SSH host available to a local client. Orca tests the route before exposing it and distinguishes an SSH policy refusal from a service that is not listening. It tracks the target and connection generation, then closes old forwards before binding replacements.
Saved forwards return after a served host reconnects. Restore and edit operations are serialized so they cannot bind one local port twice. A forward that fails repeatedly backs off without deleting the user's saved mapping.
References: src/…/ssh-port-forward-handlers.ts• L13-156 src/…/ssh-port-forward-persistence.ts• L13-103 src/…/ssh-managed-port-forward-restore.ts• L11-95 src/…/ssh-tcp-forwarding-probe.ts• L1-145
Unmanaged SSH terminals
When a host cannot move to a managed Orcad service, Orca can open one plain SSH terminal for the blocked host. This is an ephemeral shell that uses the user's SSH configuration. It does not create an Orca workspace, restore a managed terminal, or mark the host as a connected Orca runtime.
References: src/…/plain-ssh-terminal-sessions.ts• L1-5 src/…/plain-ssh-terminal-sessions.ts• L106-212 src/…/ssh.ts• L109-115
Managed Orcad services
A managed Orcad service turns a remote host into a durable Orca runtime. On connect, Orca uses an existing service when possible, deploys one to an empty host, or converts existing direct-SSH state. The host is marked unavailable when safety or reachability cannot prove that the managed route is ready.
Managed service setup
Setup checks the host platform, home directory, runtime support, service identity, and readiness before it activates the service. A launch that exits or fails readiness is distinct from a loss of contact, so the user can tell whether the host answered with a refusal.
The host claim and activation record prevent two desktops from changing one data root at the same time. An interrupted or rejected update keeps a recovery path. Orca does not stop the current service until candidate checks and live-terminal checks permit the change. Setup remedies tell the user whether to retry, free space, stop an unmanaged runtime, or inspect details.
References: src/…/ssh-host-server-on-connect.ts• L27-71 src/…/ssh-host-server-on-connect-wiring.ts• L42-190 src/…/ssh-host-server-setup-remedy.ts• L1-27 src/…/SshHostRecoverServerAction.tsx• L33-53
Managed tunnel transport
The normal managed route forwards SSH traffic to the Orcad loopback service. If the SSH host rejects TCP forwarding, Orca can use a standard-input/output bridge over an SSH command channel when the host supports it. Both routes present the same paired runtime interface to the desktop.
The tunnel is tied to the SSH target, connection, service identity, and current service port. A changed port or replaced connection creates a new verified route instead of reusing an old forward.
References: src/…/runtime-environment-managed-tunnel.ts• L55-95 src/…/ssh-host-server-connect.ts• L27-37 src/…/ssh-tcp-forwarding-probe.ts• L31-68
Managed service recovery
Every managed runtime call can restore the service after an idle stop, host restart, process loss, or another desktop's action. Orca restores the tunnel, checks that the service answers, and starts or redeploys it when needed. It rebuilds forwards when the service port changes.
Updates and recovery protect live terminals with a host-wide census. An unanswered census is not treated as an empty host. Stop, forget, and unavailable states remain distinct so an uncertain remote service is not silently removed.
References: src/…/orcad-runtime-maintenance.ts• L53-319 src/…/orcad-active-readiness.ts• L86-161 src/…/orcad-daemon-protocol-crossing.ts• L18-79 src/…/ssh-host-sleep-reconnect.ts• L23-30
Managed service migration
Migration moves host-owned catalog rows and dormant workspace state from direct SSH storage to the managed service without losing a recoverable source. The source stays fenced until destination ownership is proven. A durable journal supports resume and abort. Later changes require an explicit delta move.
The user can move new projects to the server or keep the server's version. The server does not silently overwrite newer server-owned state. Removing a managed SSH target also requires Stop or Forget so the service is not stranded on the host.
References: src/…/orcad-migration-manifest-export.ts• L44-172 src/…/orcad-migration-cutover-coordinator.ts• L42-293 src/…/orcad-migration-source-fence.ts• L37-66 src/…/SshHostDeltaMoveDialog.tsx• L30-159 src/…/SshHostKeepServerVersionDialog.tsx• L16-84 src/…/SshManagedHostRemoveDialog.tsx• L14-59
Legacy relay continuity
Older SSH-host terminals can remain reachable through a legacy relay while a host changes to a managed service. The bridge owns the relay terminal lease, sends data and screen replay to the desktop, and reports an exit only when the old relay proves it.
Loss of relay contact leaves a pane unverifiable. A closed pane records its requested stop before the relay reports its exit. Hidden panes suppress bulk output and request one ordered screen replay when they become visible. This keeps old terminals usable without treating a lost connection as proof that a process ended.
References: src/…/legacy-relay-bridge-application.ts• L19-91 src/…/legacy-relay-bridge-ipc.ts• L32-86 src/…/legacy-relay-bridge-registry.ts• L65-95 src/…/legacy-relay-bridge-registry.ts• L187-353 src/…/legacy-relay-hidden-output.ts• L24-175 src/…/legacy-relay-hidden-output.test.ts• L4-16
Remote workspace projection
Remote workspace projection keeps the desktop view aligned with the host that owns each workspace. Runtime calls publish remote sessions and terminal state. Direct SSH work stays attached to its SSH target. The desktop keeps host-private session data separate from client-wide focus and layout data.
Host-owned session state
Workspace session state is partitioned by execution host. A partition contains host-owned terminal and session identities, while the desktop can combine those partitions into one view. This prevents a local session and a remote session with the same repository or worktree name from being merged.
Target ID migration updates the persisted carriers that point to a host, including terminal IDs, workspace sessions, folder workspaces, project groups, and visible host order. This keeps a re-adopted host connected to the work that already belongs to it.
References: src/…/runtime-client-state.ts• L110-119 src/…/execution-host.ts• L205-254 src/…/ssh-target-id-migration.ts• L35-160
Terminal ownership
Before Orca creates or resumes a terminal, it resolves the workspace owner and checks the terminal's own host identity. An explicit worktree host outranks its repository host. If the owner cannot be proved, Orca returns an unresolved result and does not create a second shell or agent session.
Malformed or foreign terminal IDs are not treated as local because a workspace has a local fallback. Reattachment binds only to a pane that the saved topology already owns.
References: src/…/worktree-execution-host-resolution.ts• L28-77 src/…/terminal-execution-host.ts• L12-37 src/…/workspace-terminal-host-authority.ts• L20-127 src/…/ssh-target-id-migration.test.ts• L34-101
Mobile workspace server routing
On mobile, the paired host can be the route owner while a different server executes the workspace. The workspace route keeps both clients visible: the server client runs workspace actions, while the paired host remains the phone's peer and supplies relay reachability and capabilities.
The route is usable only when the server is reachable and the paired desktop can relay the requested capability. An absent server context means normal desktop routing. A null server client means the selected server is unavailable, not that the workspace should run locally.
References: mobile/…/use-workspace-client.ts• L7-35 mobile/…/workspace-server-context.ts• L6-19 mobile/…/workspace-server.ts• L13-68 mobile/…/host-status-gates.ts• L75-132
WSL host workspaces
WSL-hosted Orcad work uses the WSL host bridge while the desktop remains the view owner. Agent launches use a program inside the distro rather than a Windows PATH shim. A Windows-only agent is refused with a fix path, while a recorded custom or absolute command remains unchanged.
References: src/…/wsl-host-agent-terminal-launch.ts• L39-146 src/…/wsl-moved-project-chat-runtime.test.ts• L96-123
Execution-host selection
Execution-host selection decides where Orca reads files, runs Git and provider commands, creates terminals, launches agents, and applies workspace actions. The selected host travels with the request so an operation for one machine cannot run on a sibling machine with the same repository ID.
Host identity and precedence
Orca uses local, runtime:<environment>, and ssh:<target> as routable host identities. A worktree's explicit host wins over its repository host. If neither is present, legacy repository connection data can identify an SSH host. Otherwise the work is local only when the data proves that it is local.
An invalid, ambiguous, or unresolved host is a routing failure. Display code may use a local fallback for an unknown row, but execution code must not use that fallback to read or mutate remote files.
References: src/…/execution-host.ts• L61-75 src/…/execution-host.ts• L204-260 src/…/worktree-execution-host-resolution.ts• L40-77
Host registry
The host registry combines saved environments, runtime status, SSH state, and workspace references into the host choices shown to the user. It reports local, connecting, available, blocked, disconnected, and error states. Protocol incompatibility blocks a runtime before Orca sends work.
Managed SSH and runtime entries are merged for selection, while internal aliases remain available for exact ownership checks. Plumbing targets used by a runtime are hidden as separate user-facing SSH targets.
References: src/…/execution-host-registry.ts• L30-49 src/…/execution-host-registry.ts• L126-304 src/…/managed-orcad-execution-host.ts• L76-112
Request route ownership
Execution-host routing covers files, Git, terminals, agents, browser sessions, worktrees, and provider calls. Untargeted requests stay on the current desktop. Targeted runtime requests are relayed only to the named environment. An unreachable target returns an error and never runs locally.
For mobile clients, the method route separates execution-host work from paired-desktop work. A workspace server route adds one more check: both the server capability and the paired desktop's relay capability must allow the operation.
References: src/…/runtime-rpc-mobile-method-routing.ts• L1-215 src/…/runtime-rpc-websocket-dispatch.ts• L43-100 src/…/runtime-provider-command-ssh-routing.test.ts• L41-78 mobile/…/use-workspace-client.ts• L12-34
Change checklist
When these files or sections are changed, remember to consider these:
- When a host ID or ownership field changes, update repository, worktree, folder workspace, PTY, session, provider, and registry routing together.
- When pairing changes, keep pairing scope, revision, runtime identity, capability evidence, status ownership, request queues, and persisted sessions aligned.
- When CLI pairing changes, preserve the early rejection of mobile-only links and the distinction between an unreachable host and a refused code.
- When runtime transport changes, preserve the choice between one-shot requests, reusable connections, shared control, and subscriptions.
- When mobile relay changes, keep sign-in requirements, active and pending paths, named reachability outcomes, and host descriptors consistent.
- When SSH config handling changes, preserve OpenSSH route resolution, included-policy uncertainty, host-key lookup names, route de-duplication, and target generations.
- When SSH trust or sign-in changes, keep host-key rejection ahead of credential fallback and keep remembered credentials bound to the effective route.
- When SSH reconnect or forwarding changes, preserve user disconnects, replacement ownership, wake retry behavior, route probes, saved mappings, and forward cleanup.
- When remote file transfer changes, preserve source checks, path containment, cancellation teardown, backpressure, and the distinction between failed and unknown remote state.
- When managed Orcad setup changes, keep host claims, readiness, activation journals, snapshots, terminal census, setup remedies, and tunnel generations aligned.
- When managed migration changes, keep destination identity, capability checks, source fencing, path rewriting, journals, delta behavior, and server-owned state aligned.
- When workspace projection changes, keep host-private session fields in the host partition and preserve the difference between proven absence, unknown ownership, and ambiguity.
- When target ID migration changes, update every persisted carrier of the old SSH target ID before allowing reconnect or reattach.
- When legacy relay changes, preserve terminal leases, exit proof, stop records, hidden-output replay, and migration continuity.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A mobile-only pairing code is used by the CLI | The CLI could save a link with the wrong access scope | Reject the code before any host request |
| A reachable host refuses a pairing code | A later connection fails with a less useful error | Probe the host and report the refusal during add |
| A targeted remote request cannot reach its host | Work could silently run on the desktop | Return an unavailable error and never fall back locally |
| Pairing revision or runtime identity changes while a call waits | Work can reach a replacement runtime with the wrong state | Check both values before dispatch |
| A workspace server is unavailable while the paired host is connected | Workspace work can run on the wrong machine | Keep server state separate and return server unavailability |
| An SSH alias has uncertain included policy | A saved target could bypass the user's host-key rules | Treat unreadable or uncertain policy as strict |
| A host key changes or cannot be identified | Orca could connect to an impersonated host | Reject before credential fallback and do not create trust |
| A newer SSH connection replaces an older one | A late handshake can publish stale state | Bind results and cleanup to the connection generation |
| The user disconnects while reconnect is queued | Background work can reopen a host the user stopped | Record the user disconnect and block automatic dials |
| A remote command or transfer closes before completion is known | A retry can duplicate a process or partial transfer | Return unresolved or unknown state |
| A saved port forward is restored during replacement | A stale listener can bind a port or reach the wrong host | Serialize changes and check the current connection generation |
| Managed service readiness or terminal coverage is unproven | Orca can activate a service that cannot serve its work | Require matching identity, readiness, and terminal evidence |
| An activation journal or terminal census is unreadable | Cleanup can remove state that may still be in use | Keep state until ownership and recovery evidence are clear |
| A migration source fence or acknowledgement is lost | Two owners can act on state whose transfer phase is unknown | Keep the source fenced and resume from proven destination state |
| A relay loses contact with a terminal | The desktop could report a false exit or strand a shell | Keep the pane unverifiable until the relay proves exit |
| Workspace ownership is ambiguous or a terminal ID is foreign | A second local shell or agent can start beside remote work | Fail closed and require a resolved execution host |
Key files
| File | Why to read it |
|---|---|
| src/…/execution-host.ts | Defines routable host IDs and host precedence. |
| src/…/worktree-execution-host-resolution.ts | Defines fail-closed worktree ownership resolution. |
| src/…/execution-host-registry.ts | Builds the user-visible host list and health state. |
| src/…/environment-pairing-exchange.ts | Shows CLI pairing scope checks and host probing. |
| src/…/runtime-environment-transport-routing.ts | Shows how runtime calls select request and stream paths. |
| src/…/runtime-rpc-websocket-dispatch.ts | Shows device authentication and execution-host relay decisions. |
| src/…/ssh-application.ts | Shows the main owner of SSH targets, connections, forwards, and relay wiring. |
| src/…/ssh-g-config-resolution.ts | Shows how Orca follows the user's effective OpenSSH route. |
| src/…/ssh-connection-manager.ts | Shows SSH connection ownership, replacement, disconnect, and recovery. |
| src/…/sftp-upload.ts | Shows safe remote upload boundaries. |
| src/…/system-ssh-file-transfer.ts | Shows platform-aware system SSH transfer. |
| src/…/ssh-host-server-on-connect.ts | Shows the choice between an existing service, deployment, conversion, and an unserved host. |
| src/…/orcad-runtime-maintenance.ts | Shows managed service update, rollback, recovery, and lifecycle fencing. |
| src/…/orcad-migration-cutover-coordinator.ts | Shows migration stages, source fencing, commit, and abort. |
| src/…/legacy-relay-bridge-registry.ts | Shows legacy terminal relay ownership and exit reporting. |
| src/…/ssh-target-id-migration.ts | Shows how target changes update persisted workspace and terminal ownership. |
| mobile/…/use-workspace-client.ts | Shows how mobile selects the workspace execution client. |