Orca: coordinate coding agents without losing track of their work
Deploy Orca headlessly: listener, display and pairing are different checks
Use the pinned Linux guide to plan a private runtime without mistaking an advertised address for network isolation.
What you will learn
- Headless still has runtime dependencies
- Bind and advertise separately
- Make service operation reversible
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
- Headless operation still depends on Electron libraries.
- Pairing address does not restrict binding.
- Runtime readiness and pairing availability can differ.
Headless still has runtime dependencies
The guide says orca serve starts without a desktop window but the packaged AppImage still needs Electron libraries. With no DISPLAY, current builds start Xvfb if installed. A stale DISPLAY referring to a dead locked process is refused rather than silently replaced.
Package names differ across Ubuntu and Debian releases, including t64 transitions. Use the guide’s list for the actual distribution. Do not copy the newest package names onto an older image and interpret missing packages as an Orca model error.
Bind and advertise separately
The --pairing-address option changes the address advertised to clients, not the listener bind address. Inspect boundEndpoint and advertisedEndpoint in --json output and enforce access through firewall or an approved private network.
The ready record may contain pairing.available:false with a reason while the server remains usable. --recipe-json requires a pairing URL and is stricter. Preserve pairing URLs privately because they are access-related material, not harmless log decoration.
Make service operation reversible
Run under a dedicated non-root service account and retain a reviewed previous artifact. The guide recommends root-owned installation files that the service can execute but not replace. Start in the foreground before introducing a supervisor.
Check restart behavior and data locations in a disposable environment before upgrading a working runtime. Stop a foreground trial with Ctrl+C. We did not install system packages, start orca serve or validate a remote pairing for this series.
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
Match Linux dependencies to the distribution.
- 2
Inspect bound and advertised endpoints separately.
- 3
Test foreground startup under a dedicated account before supervision.
Copy-ready example
orca serve --port 6768 --json
# Keep any pairing URL private; stop the foreground trial with Ctrl+C.Frequently asked questions
Does --pairing-address make the listener private?
No. Apply a real network-access policy and inspect boundEndpoint.
Must pairing always exist in ready output?
The documented object can report available:false with a reason.
Sources
- Orca / docs/reference/headless-linux-server.mdSource checked 2026-09-18