3. requireHand re-pairing.

back to the service

pkill -f 'cli/index.js serve'
orca-ide serve service install         # writes the unit, enables it, starts it

CheckThis whocreates ~/.config/systemd/user/orca-serve-<hash>.service, which runs orca-ide serve --supervise --no-pairing with ORCA_USER_DATA_PATH set. Linger is pairedalready on (loginctl show-user conor --property=Linger), so it starts at anyboot timewithout (read-only,anyone logging in.

4. Check it

orca-ide serve service status
ss -tlnp | grep 6768                   # orcad listening on 0.0.0.0:6768
pgrep -af orcad-server.js              # exactly one, running from ~/.orca
ls ~/.config/orca 2>/dev/null || echo "good, no tokensstray printed):profile"

List paired devices:

python3 -c "
import jsonjson; for d in json.load(open('/home/USERNAME/.orca/orca-devices.json')):
    [print(d['scope'].ljust(8), d['name'].ljust(45), d['deviceId']) for d in json.load(open('$HOME/.orca/orca-devices.json'))]"

Troubleshooting

4.Install

(§3).

KillMode=process

— stopping the service stops the server but leaves the terminal daemon and your terminals alive.

---

Symptom	Fix
[1]+ Stopped orca-ide serve ...	It was run in a terminal. Kill it with kill -9 -- -<pid> and use the setsid command from step 2
orcad_instance_lock_held	Another server owns the profile. Stop the service or pkill -f 'cli/index.js serve'
Error mentions ~/.config/orca	ORCA_USER_DATA_PATH isn't set in that shell. Run rm -rf ~/.config/orca and fix step 1
Desktop over SSH shows an empty workspace	Same cause: the export is below the interactive check in ~/.bashrc
Service starts then immediately stops	The supervisor gave up. Check orca-ide serve service installstatus --dry-and run # prints the unit, writes nothing orca-ide serve service install again
start request repeated too quickly	systemctl --user reset-failed 'orca-serve-*.service'
Pairing link rejected	The installoffer writesexpired. this unit, then runs daemon-reload, enable and restart — i.e.Restart the server starts immediately. ~/.config/systemd/USERNAME/orca-serve-3eba5288.service (the 3eba5288 suffix is derived from ORCA_USER_DATA_PATH; the default profile would give plain orca-serve.service) [Unit] Description=Orcapairing server (orca serve --supervise) StartLimitIntervalSec=900 StartLimitBurst=5 [Service] Type=simple ExecStart=/home/USERNAME/.local/bin/orca-ide serve --supervise --no-pairing Environment=ORCA_USER_DATA_PATH=/home/USERNAME/.orca Restart=on-failure RestartSec=10 TimeoutStopSec=90 KillMode=process [Install] WantedBy=default.target Why the flags matter: --supervise — restarts with backoff, waits (instead of dying) while the app updates or another Orca serves the profile, and gives up cleanly after 6 failures in 15 minutes. --no-pairing — no live offer in the journal. Pairing isfor a manualfresh stepone

5.Quick Verifyreference

orca-ide serve service status | install | uninstall
systemctl --user statusstop|start 'orca-serve-*.service' --no-pager
journalctl --user -u 'orca-serve-*.service' -n 50 --no-pager
ss -tlnp | grep 6768
orca-ide status

Expect: unit enabled + active (running), runtimeState: ready, runtimeReachable: true. There will be no pairing link in the log — by design.

6. Reboot survival

loginctl show-user USERNAME --property=Linger --value
systemctl --user is-enabled 'orca-serve-*.service'

With lingering on, the user manager starts at boot without anyone logging in, so the server comes up on its own. Verify for real with a reboot, then re-run the checks in §5.

What survives vs. what doesn't:

• Survives: the server, pairings, terminal journal, orchestration DB.
• Does not survive: live processes inside terminals. Orca restores sessions from its journal, but large restores are throttled — agents may come back asleep and resume when you open them. orca-ide serve restore resume clears a paused restore.

Reboot gotchas:

• Give-up brake is on disk at ~/.orca/serve-supervisor-brake.json, keyed by build. Once the supervisor gives up, a reboot will not retry — the unit exits 0 immediately. Fix the cause, re-run orca-ide serve service install (that clears the brake), or orca-ide serve --supervise --force once outside the service. serve service status reports gaveUp.
• systemd's own limit (5 starts / 900s): systemctl --user reset-failed before it will try again.
• The unit has no After=network-online.target. Fine today (binds loopback, no pairing offer). Add ordering if you ever depend on Tailscale being up at boot.

Multiple devices

Yes — multiple devices can be paired, and this profile already has five:

Details worth knowing:

• Each device gets its own deviceId and token, tracked in ~/.orca/orca-devices.json. No device cap is enforced in this build.
• runtime scope = the desktop/CLI client; mobile scope = phone. A mobile device records the parentDeviceId of the runtime device that invited it.
• Offsets of the scale: offers are single-device. Pair each device from its own foreground orca-ide serve run (or --mobile-pairing for a phone), or mint more offers from a desktop app that is already paired.
• Manage/revoke from the desktop app's device list. Hand-editing orca-devices.json only takes effect with the server stopped, and is easy to get wrong — prefer the app.

Troubleshooting

Rollback

orca-ide serve service uninstall      # stops it, removes the unit; daemon + terminals stay

Then, if you want the old headless runtime back, start orcad manually (it is not supervised and will not survive a reboot).

Quick reference

export ORCA_USER_DATA_PATH=/home/USERNAME/.orca

orca-ide serve                        # foreground server, prints pairing link
orca-ide serve --mobile-pairing       # phone QR / link
orca-ide serve service install        # install + enable + start the unit
orca-ide serve service status         # is it installed / live / gave up?
orca-ide serve service uninstall      # stop + remove
orca-ide serve restore resume          # un-pause throttled session restores orca-ideafter statusa # runtime reachability for this profilereboot