Orca ADE

Orca is an agent development environment — it runs coding-agent CLIs (Claude Code, Codex, OpenCode and ~30 others) in parallel git worktrees behind one UI. The dev VM runs Orca headless, so the VM owns the repos, worktrees, terminals and agent sessions while you drive it from your own laptop, browser or phone.

Set up 2026-09-18 on deployd-dev (Ubuntu 26.04), Orca v1.4.205.

The practical difference from running Orca locally: agents keep running when your laptop sleeps, disconnects or reboots, because they are processes on the VM, not on your machine. It is the same property that makes zellij sessions survive there.

What runs where

Your machine · Orca client (desktop app, browser or phone)
  Shows the UI and sends your input
                 │
                 │ Tailscale (WireGuard) — never the public internet
                 ▼
deployd-dev · Orca server  100.113.53.51:6768
  Owns repos, worktrees, terminals, agent sessions
  Runs claude / git / docker as the `deployd` user

Remote sessions use the server’s PATH, home directory and credentials — never your machine’s. Three consequences follow, and they are the whole of what you need to understand before pairing.

Danger

Pairing is equivalent to being handed a root shell on the dev VM. The server runs as deployd, which has unrestricted $HOME, passwordless sudo and membership of the docker group. That is deliberate — the point of the server is to drive this machine — but pair only devices you would trust with root, and tell an operator if a paired device is lost.

Caution

Agent runs spend the server’s Claude subscription, not yours. Claude Code is installed and logged in on the VM, and agents inherit that login because they run as deployd. You do not need to log in, and your usage is not billed to you. Be considerate with long agent fleets.

Note

Anything you start keeps running after you disconnect. That is the feature, but it also means an abandoned agent keeps consuming the VM’s CPU and RAM. The box has 8 vCPU, 31 GiB and no swap, shared with 36 Coolify containers — close worktrees you are done with.

Prerequisites

1. A tailnet invite. The server is reachable only from the tailnet (tail4d9159.ts.net, owner ajaym94@) and the LAN — it is on no Cloudflare tunnel and has no public hostname. Ask an operator for an invite, then install the Tailscale client and sign in. tailscale status should list deployd-dev.

2. Orca on your own machine, unless you plan to use the browser client:

   brew install --cask stablyai/orca/orca     # macOS
   yay -S stably-orca-bin                     # Arch

   Windows, Linux AppImage and the mobile apps are at onorca.dev/download.

Pair your machine

Ask an operator for a pairing link. They get it from the server:

ssh dev
jq -Rrc 'fromjson? | select(.type=="orca_server_ready") | .pairing.url' \
  ~/.local/state/orca-serve.out | tail -1

Caution

A pairing link is a credential, not an address — it carries a device token and end-to-end encryption key material. Treat it like a password: accept it over a private channel, use it once, and never paste it into a shared channel, a ticket or a commit.

Then, whichever client you prefer:

Client	How
Desktop app	Settings → Remote Orca Servers → Add Server. Paste the link, name it dev-vm, click Add Server. If the row shows Disconnected, click Connect.
Browser — nothing to install	Ask for the webClientUrl instead of the pairing.url. It is http://100.113.53.51:6768/web-index.html#pairing=… and pairs and connects in one step.
CLI	orca environment add --name dev-vm --pairing-code "orca://pair?code=…", then orca environment list.
Phone	Needs a mobile-scoped QR, which an operator has to mint deliberately. Note that background push notifications do not fire from a headless server.

Once the server shows Connected, pick it (or one of its projects) and use Orca normally. Open Advanced → Active Server only if you want new projects, terminals and browser handoff to default to the server.

Each teammate needs their own link — a pairing offer is bound to one device. Ask rather than forwarding someone else’s.

Things that will confuse you otherwise

orca on the server is not the Orca CLI

If you SSH to the dev VM yourself, the command is orca-ide, not orca:

command -v orca        # → ~/.orca-relay/bin/orca   ← an SSH bridge shim, not the CLI
command -v orca-ide    # → ~/.local/bin/orca-ide    ← the real CLI

Upstream names the Linux CLI orca-ide so it never shadows GNOME Orca’s screen reader, and on this host a leftover SSH-bridge shim owns the bare name and wins on PATH. Typing orca will appear to work and then refuse to do server-side things.

A server restart ends your running agents

Restarting the Orca service kills every live terminal and agent for every paired client. The persisted layout and terminal history survive, and an agent conversation may be resumable, but in-flight work is gone. Operators are asked to check before restarting; if your session goes quiet and reconnects empty, that is the likely reason.

Your machine’s logins do not carry over

Install and authenticate any CLI you need on the server, not on your laptop. A gh auth login on your machine has no effect on what an agent can do on the VM. The VM’s gh is authenticated as ajaym94, so commits and pushes an agent makes come from that account.

Related

• Dev VM Shell — the zsh/Starship environment agents run inside.
• Contributing — repo layout and the submodule rules.
• ops/orca/README.md in MasterControl — the operator-side runbook: install, upgrade, revoke grants, and the traps found while setting this up.