Orca: coordinate coding agents without losing track of their work
Orca architecture: distinguish workspaces, remote hosts and relay cells
Map local coding work, headless runtime access and the documented mobile relay without assuming all traffic uses one path.
What you will learn
- Local task state and remote execution
- The mobile relay has its own components
- Push is not the relay data path
Before you start
- Basic command-line and configuration reading
- Ability to work in a disposable authorized environment
Create a learning tool that records host, worktree and acceptance evidence without automating merges or deleting unfinished work.
Key takeaways
- A path without its host can be ambiguous.
- The relay uses an independent workspace.
- Push notifications and relay traffic are different paths.
Local task state and remote execution
Worktrees organize checked-out repository state, while terminals run the selected agent or shell. For remote work, files and processes can reside on another host. Record the execution host as well as the worktree path to avoid inspecting the wrong machine.
The headless guide exposes an explicit runtime-ready contract with bound and advertised endpoints. A client connection needs the reachable advertised destination, while operators must secure the actual listener. These are separate roles in the architecture.
The mobile relay has its own components
The cloud README describes phones and desktop hosts opening outbound WebSockets to relay cells. A director assigns hosts and coordinates migrations; cells carry connections. This describes the relay path, not every direct runtime or SSH connection.
The cloud directory is an independent pnpm workspace. Its relay contract, server and operations components are distinct from the desktop root package. Building the desktop does not mean a private relay deployment has been configured.
Push is not the relay data path
The same document separates the mobile push gateway from the relay. It sends provider notifications through APNs and FCM. A banner arriving on a phone is therefore not equivalent to proof that an interactive relay session is healthy.
The README notes limitations of offline FCM notification delivery. Monitor execution, connection and notification outcomes separately. We inspected the documented decomposition but did not audit encryption implementation or run mobile delivery tests.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Record the host for each task and terminal.
- 2
Separate relay cells and director from direct runtime endpoints.
- 3
Track push delivery independently of interactive sessions.
Copy-ready example
Task → worktree + terminal on selected host
Phone / desktop → relay cell ← director assignment
Desktop → push gateway → APNs / FCMFrequently asked questions
Does a notification prove the task succeeded?
It is a notification event; inspect the task result and connection state.
Does building the desktop deploy a relay?
The relay has its own workspace and setup requirements.
Sources
- Orca / README.mdSource checked 2026-09-18
- Orca / docs/reference/headless-linux-server.mdSource checked 2026-09-18
- Orca / cloud/README.mdSource checked 2026-09-18