Skip to main content

Orca IDE server setup

Orca IDE server setup

Tested against Orca 1.4.243 (orcad 0.1.0) on Debian 13. Updated 2026-10-28.

Gotchas

  1. The live profile is ~/.orca, not the default ~/.config/orca. Every orca-ide command must have ORCA_USER_DATA_PATH set. Otherwise it quietly starts a second, empty server in ~/.config/orca and you get orcad_instance_lock_held errors.
  2. orca-ide serve gets paused when run in a terminal. It starts bash -ilc to read your environment, and that shell grabs the terminal, so the whole job ends up Stopped. kill -CONT doesn't help. Always run it detached with setsid (see step 2).
  3. Use orca-ide, not orca. /usr/bin/orca is the GNOME screen reader.

Pair a new phone (service already running)

Stop the service, run a pairing server, scan the QR, then start the service again.

# 1. Stop
systemctl --user stop 'orca-serve-*.service'

# 2. Pair
setsid nohup orca-ide serve --mobile-pairing --pairing-address 100.64.0.4 \
  </dev/null >/tmp/orca-serve.log 2>&1 &
sleep 15; cat /tmp/orca-serve.log

Scan the QR with the Orca app, or open the orca://pair?code=... link on the phone. Once the phone shows it's connected:

# 3. Start
pkill -f 'cli/index.js serve'
systemctl --user start orca-serve-3eba5288.service
systemctl --user is-active orca-serve-3eba5288.service   # should print: active

The phone stays paired after the switch back. If cat shows no QR yet, wait a few seconds and run it again.

1. One-time: set the profile path

Put this at the top of ~/.bashrc, above the case $- in ... return block. If it sits below that block, non-interactive SSH sessions (the Orca desktop app) never see it:

export ORCA_USER_DATA_PATH="${ORCA_USER_DATA_PATH:-$HOME/.orca}"

Check it from another machine:

ssh conor@cbfarm 'echo $ORCA_USER_DATA_PATH'   # should print /home/conor/.orca

2. Pair a device

The service runs with --no-pairing, so to pair you stop it and run a pairing server by hand.

systemctl --user stop 'orca-serve-*.service'
pkill -f 'cli/index.js serve'          # any leftover manual server

# Phone (use the Tailscale IP so the phone can reach it)
setsid nohup orca-ide serve --mobile-pairing --pairing-address 100.64.0.4 \
  </dev/null >/tmp/orca-serve.log 2>&1 &

sleep 15; cat /tmp/orca-serve.log      # scan the QR, or open the orca://pair?code=... link

For a desktop or CLI client, leave out --mobile-pairing.

  • Each offer pairs one device and expires quickly. For the next device, run pkill -f 'cli/index.js serve' and start it again.
  • Pairings persist across restarts and reboots.

3. Hand back to the service

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

This creates ~/.config/systemd/user/orca-serve-<hash>.service, which runs orca-ide serve --supervise --no-pairing with ORCA_USER_DATA_PATH set. Linger is already on (loginctl show-user conor --property=Linger), so it starts at boot without 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 stray profile"

List paired devices:

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

Troubleshooting

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 status and run serve service install again
start request repeated too quickly systemctl --user reset-failed 'orca-serve-*.service'
Pairing link rejected The offer expired. Restart the pairing server for a fresh one

Quick reference

orca-ide serve service status | install | uninstall
systemctl --user stop|start 'orca-serve-*.service'
journalctl --user -u 'orca-serve-*.service' -n 50 --no-pager
orca-ide serve restore resume          # un-pause throttled session restores after a reboot
Back to top