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 / command-line-and-headless-runtime

Command-line and headless runtime

Orca gives people, agents, and scripts one way to run work with or without a desktop window. The CLI validates a command, selects the execution host, sends an RPC request, and formats the result. A local or paired runtime owns the work. Headless serve mode keeps that runtime available on an unattended machine, while SSH and the terminal daemon carry the host and session boundaries that make remote work safe. For the parent platform, see Desktop app platform. For renderer behavior, see Desktop renderer experience. For transport detail, see Relay protocol and transport. For saved state, see Desktop persistence and lifecycle. For browser work, see Browser automation and embedded web.

Runtime model

Command-line client

The CLI is a command client, not a second owner of runtime state. It turns a command into a validated RPC call and presents the result for a person or a script. Command specs and handler groups keep help, aliases, allowed flags, dispatch, and machine discovery in one contract. src/…/index.ts and src/…/handler-group-manifest.ts define this boundary.

The CLI accepts command text from a flag, a file, or standard input. It keeps human output separate from JSON output so diagnostics and progress do not corrupt a machine result. A command may target workspaces, terminals, agents, chats, browser pages, bots, automations, or orchestration resources through the same client path.

References: src/…/index.ts• L51-120 src/…/args.ts• L65-125 src/…/command-body-input.ts• L39-77 src/…/handler-group-manifest.ts• L20-70

CLI installation boundary

CLI installation uses the operating system's user boundary when it must change protected state. macOS uses an administrator prompt for privileged work. Windows writes the user PATH with a bounded retry because repeating that fixed write is safe. This work changes how the CLI is found; it does not select or own a runtime.

References: src/…/cli-privileged-processes.ts• L6-16 src/…/cli-privileged-processes.ts• L22-49

Runtime authority

The selected runtime owns durable work and caller scope. A local route uses this profile. A paired route uses a saved runtime or pairing code. An orchestration --on route keeps the command client on the caller's Orca while that Orca carries the request to a named server.

Explicit local selection suppresses ambient remote settings. Local-only commands such as account, authentication, profile, host management, serve, and local authoring refuse remote selection. Host and workspace selectors must identify the execution host; the caller's current directory is not a path on a remote machine.

References: src/…/index.ts• L121-181 src/…/remote-selection-scope.ts• L1-21 src/…/remote-server-selection.ts• L7-43 src/…/wsl-caller-distro.ts• L3-9

Result recovery

The CLI distinguishes a refused request from a request whose result is unknown. Mutations can carry a request identity, so a timeout or lost reply can be checked or replayed instead of starting a second action. Long waits receive transport grace and keepalive support. A compatibility check can refuse an old runtime before it changes state.

This contract matters most for agent launch, terminal creation, orchestration, and automation writes. A successful acceptance result means that the runtime accepted the work. It does not always mean that the final workspace, terminal, or agent is already ready.

References: src/…/client.ts• L95-198 src/…/client.ts• L201-228 src/…/client.ts• L282-307 src/…/agent-launch-request.ts• L123-175

Headless launch paths

Serve mode

orca serve starts an RPC runtime without opening a desktop window. It binds the service, creates the requested pairing scope, starts runtime services, and publishes readiness only after the host can answer requests. It can print human output, one JSON readiness record, or recipe data while a detached server remains active.

The launch path pins one absolute user-data path through the child process. The app chooses orcad when the packaged Node host can serve the profile. It keeps Electron serve when a desktop-owned update handoff is needed. The two hosts share the profile lock and refuse a second owner.

This diagram shows the main serve boundary.

flowchart LR
    A[orca serve] --> B[Pin user-data path]
    B --> C[Choose serve host]
    C -->|orcad| D[Start headless host]
    C -->|Electron| E[Start Electron serve]
    D --> F[Start runtime and terminal services]
    E --> F
    F --> G[Bind RPC and pairing]
    G --> H[Publish readiness and health]

References: src/…/serve.ts• L4-55 src/…/launch.ts• L147-220 src/…/serve-orcad-launch.ts• L27-117 src/…/launch-user-data-path.ts• L10-43

Headless host

orcad is the runtime host for an unattended machine. It restores profile authority, prepares host credentials and launch state, starts runtime services and terminal services, exposes RPC, and runs scheduled work without a renderer. Its readiness health describes whether runtime work is usable. It does not promise that a desktop window exists.

The host can keep a terminal daemon alive outside the desktop process. The launcher passes the user-data path, endpoint identity, access token, PID record, and launch nonce to the detached child. It adopts an already serving endpoint when another launch wins the race, and it falls back to a degraded mode when the endpoint stays usable but a fresh daemon cannot safely publish.

References: src/…/daemon-launched-child-spawn.ts• L24-43 src/…/daemon-launched-child-spawn.ts• L81-157 src/…/daemon-out-of-process-launcher.ts• L93-137 src/…/daemon-out-of-process-launcher.ts• L204-280

Supervised service

orca serve --supervise places the outer process under launchd or a systemd user service while Orca owns restart policy. The supervisor waits during update or profile contention, retries unexpected exits with backoff, and stops retrying after repeated failure. A supervised orcad host does not start without durable terminal ownership because a service restart must not destroy new terminals.

The service install commands create a stable per-user unit and disable live pairing links in service logs. Linux logout survival depends on user-manager lingering. Windows does not provide this built-in service path.

References: src/…/serve.ts• L82-127 src/…/serve-service.ts• L111-159 src/…/serve-supervised-service.ts• L69-147 src/…/orcad-serve-supervision.ts• L5-21

Readiness boundary

Readiness is the hand-off from a host to its caller. It reports the runtime identity, bound and advertised routes, pairing state, and host health. A deployer can use it to reject a server whose terminal service is not usable.

The bound route is where the host listens. The advertised route is what a client should use and can differ when an operator supplies a pairing address. A loopback-only host does not publish a false public address; pairing or an SSH route supplies the client path.

References: src/…/orcad-serve-readiness.ts• L7-20 src/…/serve-readiness.ts• L59-124 src/…/runtime-rpc-pairing.ts• L146-223

Host lifecycle boundaries

Profile identity

The user-data path is the identity boundary for a local runtime. It locates profile state, runtime metadata, pairing records, service state, and launch handoff data. The CLI passes the same absolute path to the launched host so a desktop, orca serve, and orcad cannot silently write different profiles.

The profile lock protects concurrent writers. Terminal ownership is separate, so a runtime restart can release the profile while persistent terminal sessions remain with their daemon. This split lets updates and app restarts preserve terminal work without allowing two runtimes to write the same profile.

References: src/…/launch-user-data-path.ts• L10-43 src/…/orcad-instance-lock.ts• L123-180 src/…/orcad-lifecycle.ts• L192-249

Desktop availability

Runtime health and desktop availability are different states. A headless host can run agents, terminals, browser work, and automations. It cannot show a window, accept desktop input, or complete a desktop-only file-opening flow. Local open can start or wait for the desktop only when the selected runtime is local.

Account sign-in follows the same host boundary. orca auth drives a sign-in owned by the host's running Orca and refuses remote selectors. A browser on another machine may approve the flow, but the resulting account state remains on the execution host.

References: src/…/client.ts• L309-319 src/…/auth.ts• L84-176 src/…/host-sign-in-driver.ts• L46-109 src/…/auth.ts• L4-31

Host environment

The execution host supplies the environment in which agent and terminal work runs. WSL hosts hydrate a limited login-shell environment for SSH, Git, proxy, certificate, and tool access without starting a stopped distro. The caller's WSL identity and path context stay separate from the selected remote host.

This boundary prevents a desktop or bridge environment from becoming an accidental source of credentials or paths for another host. A missing host capability is reported as a capability gap instead of being treated as a working local feature.

References: src/…/orcad-wsl-host-login-environment.ts• L47-89 src/…/wsl-caller-distro.ts• L3-9 src/…/agent-launch-request.ts• L115-160

Automation command contracts

Agent launch

orca agent launch starts an agent in an existing workspace as a chat or terminal surface. The execution host chooses the default surface from its settings and capabilities. An explicit surface, prompt, model, or effort becomes part of the launch contract and is refused when the host cannot honor it safely.

The result identifies the surface, handle, workspace, reason, and operation identity. If the reply is lost, the caller reuses the operation identity on the same host rather than creating a fresh launch.

References: src/…/agent-launch.ts• L4-33 src/…/agent-launch-request.ts• L71-105 src/…/agent-launch-request.ts• L123-189

Scheduled automation

An automation stores a prompt, a provider or bot, a schedule or event rule, a target, and optional precheck state. Project automations use a repository, workspace, or project host setup. Bot automations use the bot's own folder and session, then choose where each result runs and appears.

Scheduled runs execute the precheck before dispatch. Manual runs intentionally skip it. The runtime checks the target and its ownership again when it writes, so a removed or re-registered SSH host cannot receive work by accident. Run history is paged and an accepted queued run is not proof that its workspace or terminal already exists.

The command contract supports both time rules and event rules. Event rules name a source and event, then use scoped filters such as place, text, person, label, or workflow run. The trigger-options command is the source of truth for events that the current bot can receive.

References: src/…/automations.ts• L25-94 src/…/automations.ts• L111-177 src/…/automations.ts• L238-285 src/…/automation-destination.ts• L40-125 src/…/automation-event-triggers-cli.ts• L26-81 src/…/automation-event-trigger-spec.ts• L138-219

Orchestration commands

Orchestration commands coordinate runs, tasks, messages, workers, approvals, and gates. A run provides a namespace and inbox; it does not start a worker by itself. Worker observation keeps task state, agent liveness, terminal resources, and host reachability distinct.

Cross-server sends use --on so the caller's Orca keeps the run and mailbox while the target server performs the work. A remote agent must not use --environment to move its mailbox to another server. Mutations retain request identity and compatibility evidence for recovery.

References: src/…/orchestration.ts• L49-145 src/…/orchestration-worker-specs.ts• L3-179 src/…/message-send-handler.ts• L73-145 src/…/orchestration-mutation-recovery.ts• L12-103

Managed server and SSH transport

Managed server ownership

Managed-server control deploys and maintains an Orca server over SSH. The desktop registry owns this control plane. It can inspect, update, roll back, stop, recover, unlink, or forget a managed host. A headless serve host serves its own runtime; it does not manage other managed servers.

An update or migration crosses a safety boundary when terminals may be live. The system preflights the candidate host, checks daemon compatibility, fences the change, and reports uncertainty when it cannot prove that a remote process or terminal ended.

References: src/…/managed-server.ts• L1-80 src/…/managed-server.ts• L25-249 src/…/ssh-target-runtime-ownership.ts• L8-24 src/…/ssh-target-orcad-preflight.ts• L29-69

SSH bridge transport

SSH carries the same runtime stream through either TCP forwarding or an exec-channel bridge. The transport above SSH stays the same, so terminal, browser, and RPC clients do not need separate remote behavior. The bridge uses framed JSON-RPC messages with keepalive and bounded payloads.

The channel distinguishes connection loss, timeout, and clean refusal. A timeout or dropped channel can hide completed host work, so callers treat the result as unverifiable instead of as absent. Windows may use a loopback route or a text-safe bridge path when direct forwarding is not available.

This diagram shows the remote request path.

sequenceDiagram
    participant C as CLI
    participant S as Local SSH transport
    participant H as Remote Orca host
    participant D as Terminal daemon
    C->>S: Select host and send RPC
    S->>H: Forward or bridge framed stream
    H->>D: Use host-owned terminal service
    D-->>H: Result or stream event
    H-->>S: RPC response or keepalive
    S-->>C: Result, refusal, or unverifiable outcome

References: src/…/remote-frame-protocol.ts• L6-89 src/…/ssh-channel-multiplexer.ts• L69-127 src/…/ssh-channel-multiplexer.ts• L199-265 src/…/system-ssh-loopback-route.ts• L33-59

SSH host transition

When a desktop connects to an SSH target, it can provision or adopt a managed orcad host. The transition proves that the old relay's terminal work is safe to hand over before it stops or changes ownership. A live or unverifiable relay terminal stays bridged or blocks the transition.

The activation fence covers preflight, transfer, stop, migration, and activation. Lost contact produces an unserved or deferred result. The next connection resumes from the recorded transition instead of redeploying without evidence.

References: src/…/orcad-migration-terminal-gate.ts• L28-77 src/…/orcad-migration-terminal-gate.ts• L106-131 src/…/orcad-migration-ssh-relay-source.ts• L48-81 src/…/ssh-target-orcad-preflight.ts• L41-69

Daemon handoff

Persistent terminal daemon

The terminal daemon is a separate host process that owns persistent PTY sessions. The desktop or headless runtime uses an authenticated control channel for requests and a stream channel for terminal data. The daemon can outlive the process that launched it, so a runtime restart does not have to end its sessions.

The daemon publishes an endpoint identity and protocol version before accepting work. Launch and adoption compare that identity with the PID record and the endpoint. A replacement must prove the old owner is gone; an uncertain endpoint is preserved rather than reclaimed. The current daemon can also retain older daemon adapters so sessions from an earlier generation remain reachable.

References: src/…/daemon-out-of-process-launcher.ts• L97-137 src/…/daemon-out-of-process-launcher.ts• L239-280 src/…/daemon-protocol-version.ts• L1-22 src/…/daemon-pty-router.ts• L30-96

Daemon protocol

The daemon RPC contract separates session creation, attachment, input, resize, flow control, inspection, snapshots, and shutdown. createOrAttach can restore an existing session or create a new one. Attach-only requests refuse to create a missing session, which protects reattach flows from turning uncertainty into a new terminal.

Protocol versions gate requests that an older daemon cannot understand. The current wire version is 61. Newer clients keep older sessions usable by routing each session to the daemon generation that owns it and by avoiding unsupported requests such as repaint on older versions.

References: src/…/daemon-rpc-contract.ts• L31-75 src/…/daemon-rpc-contract.ts• L77-121 src/…/daemon-rpc-contract.ts• L197-242 src/…/daemon-protocol-version.ts• L22-84

Terminal session lifecycle

The daemon owns the full terminal session lifecycle. It admits create or attach work, starts a shell with a host-specific environment, holds automatic startup input until shell readiness, and exposes control and inspection operations through RPC. A readiness timeout releases the held work with a recorded timeout state rather than leaving a session blocked.

Input flow control has separate client and stream pauses. The daemon releases a pause when its owner disappears or termination begins, while a lost resume signal cannot release an unrelated pause. A repaint request changes only the PTY size briefly on supported systems, so the running program redraws without moving the renderer's read grid.

References: src/…/daemon-request-router.ts• L70-121 src/…/terminal-host.ts• L80-123 src/…/session-shell-ready-barrier.ts• L37-60 src/…/session-shell-ready-barrier.ts• L179-203 src/…/session.ts• L138-180 src/…/session-repaint-nudge.ts• L8-41

Terminal launch environment

Every daemon-created terminal gets a fresh environment derived from the execution host and the request. The daemon removes inherited pane, viewer, server, and agent ownership markers unless the request explicitly supplies them. This keeps a persistent daemon from giving a new terminal the identity or credentials of the process that launched the daemon.

Shell selection then applies platform rules for Unix shells, PowerShell, Git Bash, and WSL. The selected working directory and shell family remain part of the spawn contract, so a remote or WSL terminal does not silently use the caller's path or shell.

References: src/…/spawn-environment.ts• L33-45 src/…/spawn-environment.ts• L174-216 src/…/spawn-environment.ts• L230-255 src/…/shell-launch-plan.ts• L62-77 src/…/shell-launch-plan.ts• L79-141

Session routing and degraded mode

The normal router sends new sessions to the current daemon and sends existing session IDs to their known owner. During a safe daemon replacement, legacy adapters continue to serve their sessions while the current daemon takes new work. This prevents a session ID from being attached to the wrong process generation.

If the daemon endpoint remains live but its host image is no longer usable, degraded mode preserves existing daemon sessions and routes fresh terminals to a local provider. Those fresh terminals do not have daemon persistence until the daemon is restarted. The system does not treat degraded service as equivalent to a healthy persistent daemon.

References: src/…/daemon-pty-router.ts• L75-96 src/…/daemon-pty-router.ts• L139-191 src/…/degraded-daemon-pty-provider.ts• L28-92 src/…/degraded-daemon-pty-provider.ts• L307-325

Terminal history

Terminal history gives a headless session a durable view that can be restored after sleep, restart, or a client that was never attached. The daemon keeps a terminal snapshot with screen state, scrollback, cursor and mode state. It can add incremental output records between full checkpoints, then replay only a valid tail during cold restore.

Restore is conservative. A torn record, sequence gap, invalid checkpoint, or oversized file falls back to a safe checkpoint or reports unreadable recovery. A failed recovery generation is protected or quarantined instead of being silently overwritten. Snapshot replay also preserves alternate-screen frames, cursor position, wide characters, links, mouse modes, and partial escape sequences so a resumed program sees the same terminal state.

References: src/…/daemon-pty-buffer-snapshots.ts• L16-45 src/…/daemon-pty-buffer-snapshots.ts• L75-177 src/…/terminal-frame-restore-sequences.ts• L12-27 src/…/terminal-frame-restore-sequences.ts• L29-87 src/…/terminal-history-incremental-restore.test.ts• L45-177 src/…/history-manager.test.ts• L70-172

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep command specs, aliases, handler keys, positional normalization, scoped help, and dispatch exports aligned.
  • Keep local-only account, auth, profile, host, serve, and authoring commands from using remote selection.
  • Keep human output, JSON results, diagnostics, pairing data, and keepalive output on separate channels.
  • Preserve the selected user-data path across CLI launch, child host, profile lock, service unit, and update handoff.
  • Keep serve readiness behind runtime, pairing, and terminal-service health. A bound socket alone is not ready.
  • Keep --environment local, ambient environment selection, and orchestration --on as different routes.
  • Define mutation identity, compatibility checks, host ownership, and unknown-result recovery before adding a write command.
  • Keep automation target, event, schedule, bot result, host generation, and run-history contracts aligned.
  • Keep SSH timeout, loss, refusal, and unverifiable outcomes distinct. Do not treat a dropped channel as proof of exit.
  • Keep daemon endpoint identity, PID records, launch nonces, protocol versions, current and legacy routes, and adoption rules compatible.
  • Keep daemon control and stream framing bounded and able to hand off bytes already read with the hello response.
  • Keep attach-only behavior from creating a missing session, and keep shell readiness from releasing startup work too early.
  • Keep terminal environment scrubbing separate from explicit per-request environment values, especially for WSL and agent ownership.
  • Keep incremental history sequence, checkpoint generation, snapshot output sequence, and cold-restore fallback rules aligned.
  • Keep degraded mode limited to fresh local terminals while existing daemon sessions retain their proven owners.
  • Keep desktop-only actions and host-local account storage out of headless success claims.

Important failure modes

TriggerConsequenceGuard
A serve child uses a different user-data pathTwo runtimes can serve or write the wrong profilePin one absolute path and reject a profile mismatch
A second process replaces a live profile lockProfile state can be corruptedRequire owner identity and exit proof before reclaim
Readiness is published before terminal service healthA deployer accepts a host that cannot preserve terminal workPublish health with runtime readiness
A timed-out mutation is retried as new workAn agent, terminal, or automation can start twiceQuery or replay the original request identity
A remote command uses the caller's cwd as a host pathWork can target the wrong checkoutRequire an explicit remote workspace or project target
An SSH channel drops after the host received a requestThe caller cannot know whether the work finishedMark the outcome unverifiable and recover by identity
A launcher reclaims an endpoint without proving its owner is deadA live daemon can lose the only path to its terminalsAuthenticate endpoint identity and preserve uncertain owners
A detached daemon inherits the desktop's IPC descriptorsA crashed desktop can keep an orphaned child aliveClose inherited descriptors while preserving only the daemon IPC channel
A daemon generation is unknown during attach or closeA session can be duplicated or killed under the wrong ownerKeep the result unknown until identity and owner are proven
An attach-only request creates an absent sessionReattach can start a duplicate terminalEnforce attach-only at the RPC contract and route
A shell-ready marker never arrivesAutomatic startup input can block or enter a user's typed lineTime out the barrier and flush held work in order
A daemon endpoint is live but its host image is goneExisting sessions may work while new persistent terminals cannotPreserve old sessions and route only fresh terminals to degraded local mode
A history log has a gap or torn tailRestore can duplicate or lose terminal outputReplay only the valid prefix and fall back to a full checkpoint
Snapshot replay keeps stale wide cells or parser tailsA resumed TUI can show corrupt rows or literal escape textBound snapshot data and preserve cursor, frame, and partial-sequence state
A headless command claims desktop successA script believes a window or desktop action completedEnforce runtime permissions and stop at the first renderer refusal
An automation target is removed or re-registered before writeWork reaches a different or missing hostFence the target generation at read and write time

Key files

FileWhy to read it
src/…/index.tsCLI validation, host selection, local routing, and orchestration --on behavior
src/…/args.tsCommand and flag parsing plus positional rules
src/…/handler-group-manifest.tsCommand groups and handler ownership
src/…/client.tsLocal and paired RPC calls, compatibility, timeouts, and mutation recovery
src/…/command-body-input.tsScript-safe body input from text, file, or standard input
src/…/cli-privileged-processes.tsOS privilege and user PATH boundaries during CLI installation
src/…/launch.tsDesktop launch, serve child creation, profile pinning, and supervision
src/…/serve-orcad-launch.tsElectron versus orcad selection and headless child launch
src/…/serve.tsServe, pairing, restore, and service command contract
src/…/orcad-entry.tsHeadless host startup and profile environment setup
src/…/orcad-serve-readiness.tsHeadless readiness and health boundary
src/…/orcad-lifecycle.tsProfile admission, bounded shutdown, and cleanup ownership
src/…/orcad-instance-lock.tsSingle-writer profile ownership and stale-lock safety
src/…/daemon-launched-child-spawn.tsDetached daemon arguments, user-data inheritance, and descriptor boundary
src/…/daemon-out-of-process-launcher.tsDaemon adoption, replacement, endpoint ownership, and degraded fallback
src/…/daemon-protocol-version.tsVersion gates that keep old daemon generations usable
src/…/daemon-rpc-contract.tsTerminal creation, attach, control, snapshot, flow-control, and shutdown contract
src/…/daemon-request-router.tsRPC requests mapped to terminal-host behavior
src/…/terminal-host.tsPTY session ownership, admission, checkpoint, inspection, and shutdown
src/…/session.tsPer-session input, output, readiness, flow control, repaint, and exit lifecycle
src/…/session-shell-ready-barrier.tsStartup command gating and shell-readiness timeout boundary
src/…/shell-launch-plan.tsHost-specific shell, cwd, WSL, and startup command selection
src/…/spawn-environment.tsPer-terminal environment isolation and ownership scrubbing
src/…/daemon-pty-router.tsCurrent and legacy daemon session routing
src/…/degraded-daemon-pty-provider.tsExisting-session preservation and fresh-spawn fallback
src/…/daemon-pty-buffer-snapshots.tsHeadless snapshots and durable history overlay rules
src/…/terminal-frame-restore-sequences.tsAlternate-screen frame and cursor restoration contract
src/…/daemon-client.tsAuthenticated daemon control and stream handoff
src/…/daemon-stream-binary-framing.tsBounded binary and legacy stream framing