Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / remote-connectivity

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 kindID formMain use
LocallocalFiles, shells, and services on this computer
Paired runtimeruntime:<environment>Orca calls, remote sessions, and host-owned workspace state
SSH hostssh:<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

TriggerConsequenceGuard
A mobile-only pairing code is used by the CLIThe CLI could save a link with the wrong access scopeReject the code before any host request
A reachable host refuses a pairing codeA later connection fails with a less useful errorProbe the host and report the refusal during add
A targeted remote request cannot reach its hostWork could silently run on the desktopReturn an unavailable error and never fall back locally
Pairing revision or runtime identity changes while a call waitsWork can reach a replacement runtime with the wrong stateCheck both values before dispatch
A workspace server is unavailable while the paired host is connectedWorkspace work can run on the wrong machineKeep server state separate and return server unavailability
An SSH alias has uncertain included policyA saved target could bypass the user's host-key rulesTreat unreadable or uncertain policy as strict
A host key changes or cannot be identifiedOrca could connect to an impersonated hostReject before credential fallback and do not create trust
A newer SSH connection replaces an older oneA late handshake can publish stale stateBind results and cleanup to the connection generation
The user disconnects while reconnect is queuedBackground work can reopen a host the user stoppedRecord the user disconnect and block automatic dials
A remote command or transfer closes before completion is knownA retry can duplicate a process or partial transferReturn unresolved or unknown state
A saved port forward is restored during replacementA stale listener can bind a port or reach the wrong hostSerialize changes and check the current connection generation
Managed service readiness or terminal coverage is unprovenOrca can activate a service that cannot serve its workRequire matching identity, readiness, and terminal evidence
An activation journal or terminal census is unreadableCleanup can remove state that may still be in useKeep state until ownership and recovery evidence are clear
A migration source fence or acknowledgement is lostTwo owners can act on state whose transfer phase is unknownKeep the source fenced and resume from proven destination state
A relay loses contact with a terminalThe desktop could report a false exit or strand a shellKeep the pane unverifiable until the relay proves exit
Workspace ownership is ambiguous or a terminal ID is foreignA second local shell or agent can start beside remote workFail closed and require a resolved execution host

Key files

FileWhy to read it
src/…/execution-host.tsDefines routable host IDs and host precedence.
src/…/worktree-execution-host-resolution.tsDefines fail-closed worktree ownership resolution.
src/…/execution-host-registry.tsBuilds the user-visible host list and health state.
src/…/environment-pairing-exchange.tsShows CLI pairing scope checks and host probing.
src/…/runtime-environment-transport-routing.tsShows how runtime calls select request and stream paths.
src/…/runtime-rpc-websocket-dispatch.tsShows device authentication and execution-host relay decisions.
src/…/ssh-application.tsShows the main owner of SSH targets, connections, forwards, and relay wiring.
src/…/ssh-g-config-resolution.tsShows how Orca follows the user's effective OpenSSH route.
src/…/ssh-connection-manager.tsShows SSH connection ownership, replacement, disconnect, and recovery.
src/…/sftp-upload.tsShows safe remote upload boundaries.
src/…/system-ssh-file-transfer.tsShows platform-aware system SSH transfer.
src/…/ssh-host-server-on-connect.tsShows the choice between an existing service, deployment, conversion, and an unserved host.
src/…/orcad-runtime-maintenance.tsShows managed service update, rollback, recovery, and lifecycle fencing.
src/…/orcad-migration-cutover-coordinator.tsShows migration stages, source fencing, commit, and abort.
src/…/legacy-relay-bridge-registry.tsShows legacy terminal relay ownership and exit reporting.
src/…/ssh-target-id-migration.tsShows how target changes update persisted workspace and terminal ownership.
mobile/…/use-workspace-client.tsShows how mobile selects the workspace execution client.