Orca IDE gives every coding agent its own git worktree, so you can hand one prompt to two agents and keep the better branch. On Linux it ships as a .deb, an .rpm and an AppImage, and the .deb installs cleanly but won’t start on a fresh Ubuntu server image until you add one audio library it forgot to depend on.
This guide gets you from a bare box to two OpenCode agents racing in separate worktrees, then merges the winner. You’ll install the package, fix that missing library, launch agents from the app and from the orca-ide CLI, and run the headless server. It was built and run in October 2026 with Orca 1.4.239 on an Ubuntu 26.04 VM, then checked on Ubuntu 24.04 and Fedora 45, and every error below came from those boxes.
Check what Orca needs before you install
Orca is an Electron desktop app (MIT licensed) that launches CLI agents you already have. It does not host models and you don’t need an Orca account to run agents, so each agent still uses its own login or API key. That matters for planning: if no agent on the machine is logged in, Orca opens a terminal that can’t do anything useful. Have these ready:
- An x86_64 or arm64 Linux desktop session
- About 600 MB of free disk for
/opt/Orca gitand a repository agents may edit- At least one agent CLI, such as OpenCode, Claude Code or Codex
Pick the package by how you want updates to arrive. The table sums up what each format did on the lab VMs:
| Format | Tested on | Updates | What happened |
|---|---|---|---|
| .deb | Ubuntu 26.04, Ubuntu 24.04 | Orca tells you, apt installs | Installs, then fails on libasound.so.2 until libasound2t64 is added |
| .rpm | Fedora 45 (SELinux enforcing) | Orca tells you, dnf installs | Pulls alsa-lib itself and starts first time; the package is unsigned |
| AppImage | Ubuntu 26.04, Ubuntu 24.04 | Self-updates | Mounted without libfuse2, but still needs the desktop GTK and ALSA libraries |
On a normal desktop install the .deb is the quickest path, so that’s the one this guide follows. Updates for the .deb and .rpm show up inside Orca with the package-manager command to run, and Orca’s install docs say to quit the app before you run it. Arch users can grab stably-orca-bin from the AUR, which the project README points to.
Install Orca IDE on Ubuntu
Orca ships a new tag almost daily (two tags landed within hours of each other while this guide was being tested), so let the GitHub API tell you the current one instead of copying a version from a page. Install jq and read the latest tag:
sudo apt update
sudo apt install -y curl jq
ORCA_VER=$(curl -s https://api.github.com/repos/stablyai/orca/releases/latest | jq -r .tag_name)
echo "$ORCA_VER"You should get a tag with a leading v. The download URL keeps that prefix and the file name drops it, which is what ${ORCA_VER#v} handles below:
v1.4.239If you want exactly the build this guide was tested with, pin the tag instead. A fast-moving app is the one place a pin earns its keep, because a broken release can land between your laptop and your colleague’s:
ORCA_VER=v1.4.239 # pin: tested release, newer tags at https://github.com/stablyai/orca/releasesDownload the amd64 package (swap amd64 for arm64 on ARM boards; the release also carries orca-ide-*.aarch64.rpm and orca-linux-arm64.AppImage) and install it with apt so the dependencies come along. The 174 MB download took 16 seconds here:
cd /tmp
curl -sLO "https://github.com/stablyai/orca/releases/download/${ORCA_VER}/orca-ide_${ORCA_VER#v}_amd64.deb"
sudo apt install -y ./orca-ide_${ORCA_VER#v}_amd64.debThe package installs the app to /opt/Orca, a menu entry called Orca, and an orca-ide command. It is not called orca on Linux because GNOME’s Orca screen reader already owns that name. Run the version check before anything else, because this is where a server or minimal image falls over:
orca-ide --versionOn both Ubuntu VMs the first run failed. The message names the missing library file, not the package that provides it:
/opt/Orca/orca-ide: error while loading shared libraries: libasound.so.2: cannot open shared object file: No such file or directoryThe package installed correctly and dpkg -l orca-ide shows it as ii, so reinstalling won’t help. The dynamic loader just can’t find one library the binary links against.
Error: “libasound.so.2: cannot open shared object file”
The .deb’s dependency list covers GTK, NSS, xdotool, xclip and even Xvfb, but not the ALSA sound library that Electron links against. The Ubuntu 26.04 and 24.04 server images in the lab didn’t have it, and installing it is harmless where it’s already present, so add it either way:
sudo apt install -y libasound2t64Then orca-ide --version prints the version you installed. The whole sequence, error included, looked like this on the 26.04 box:
Ubuntu 24.04 uses the same libasound2t64 package name, so the fix is identical on both LTS releases.
Install the Orca rpm on Fedora
Fedora does not need the library fix, because the rpm pulls alsa-lib and about 238 other packages on a minimal Cloud image. The base image there had no jq, so read the tag with grep and cut instead, then hand the URL straight to dnf:
ORCA_VER=$(curl -s https://api.github.com/repos/stablyai/orca/releases/latest | grep -m1 '"tag_name"' | cut -d '"' -f 4)
sudo dnf install -y "https://github.com/stablyai/orca/releases/download/${ORCA_VER}/orca-ide-${ORCA_VER#v}.x86_64.rpm"
orca-ide --versiondnf finishes with a warning you should read rather than skip past, since it means nothing verified who built the file:
Warning: skipped OpenPGP checks for 1 package from repository: @commandline
Complete!The release assets are not signed, so you’re trusting GitHub’s TLS and the stablyai account. SELinux stayed in enforcing mode on that VM and the binary started without any policy change.
Run the AppImage instead
The AppImage is the only format that updates itself, which makes it the better pick if you do not want to re-run apt every other day. Download it from the stable latest link and mark it executable:
mkdir -p ~/Applications && cd ~/Applications
curl -sLo Orca.AppImage https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage
chmod +x Orca.AppImage
./Orca.AppImage --versionOlder guides tell you to install libfuse2 for every AppImage. This one mounted without it on both Ubuntu releases. What it does need is the desktop libraries, so on a clean 24.04 server image it stopped one library earlier than the .deb did:
/tmp/.mount_Orca.AeBKPcm/orca-ide: error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file: No such file or directoryOn a desktop session those GTK libraries are already present. If you hit this on a stripped image, installing the .deb once and adding libasound2t64 brings in the whole set, after which the AppImage printed its version too.
Install the agents Orca will launch
Orca only finds agents that are already on your PATH, so install them before the first launch. OpenCode is the one to start with if you don’t have a paid plan, because it ships free models that work without signing in. These three were installed for this guide, each with its own official installer (on Fedora, install nodejs and npm with dnf instead of apt):
curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://claude.ai/install.sh | bash
sudo apt install -y nodejs npm
sudo npm install -g @openai/codexThe OpenCode installer adds ~/.opencode/bin to ~/.bashrc and Claude Code lands in ~/.local/bin. The lab exported both directories in the current shell rather than opening a new one, which is the quickest way to confirm each agent answers:
export PATH="$HOME/.opencode/bin:$HOME/.local/bin:$PATH"Then check the versions:
opencode --version
claude --version
codex --versionEach one prints a version. A command not found here usually means the installer’s PATH line hasn’t been loaded into this shell yet:
1.19.4
2.1.310 (Claude Code)
codex-cli 0.164.0Claude Code and Codex still need you to log in (claude and codex login) before they’ll do work inside Orca. If OpenCode is new to you, the OpenCode install walkthrough covers its first run. The OpenCode CLI cheat sheet lists the free models and the /connect flow for adding a paid provider later, while the Claude Code cheat sheet and Codex CLI reference cover their logins and flags.
Error: “this CPU is missing SSE4.2 support, which Bun requires”
OpenCode and the Claude Code installer are both built on Bun, and Bun won’t start on a CPU without SSE4.2. You’ll only see this inside a VM whose virtual CPU hides host features, such as the kvm64 type Proxmox uses when a VM has no CPU type set. VMs created in the Proxmox web UI default to x86-64-v2-AES, which includes SSE4.2, so you’re most likely to hit this on clones of older templates. Orca itself ran fine on that CPU, so the failure looks unrelated until you read it closely.
error: this CPU is missing SSE4.2 support, which Bun requires.
If this is a VM, enable host CPU passthrough (e.g. -cpu host for QEMU/KVM).
Installation was killed before it could finish (exit code 134).Shut the VM down, set its CPU type to host (on Proxmox: qm set <vmid> --cpu host), start it again and re-run the installers. grep -m1 -o sse4_2 /proc/cpuinfo should print sse4_2 once the flag is passed through.
Pick a default agent and add a project
Start Orca from a terminal where your agents resolve, which is how the lab launched it: /opt/Orca/orca-ide &. The app menu entry works too, but it only finds agents that are on your desktop session’s PATH, and an installer that edited ~/.bashrc isn’t on it until you log in again. If an agent is missing, Settings, Agents lets you set its binary path. The four-step onboarding opens on the agent picker, and it found all three CLIs plus Claude Agent Teams, Orca’s own launcher for Claude Code teams:
Look at the Yolo mode switch before you click Continue, because it is on by default. With it on, Orca launches Claude with --dangerously-skip-permissions and Codex with --dangerously-bypass-approvals-and-sandbox, so agents edit files and run commands without asking. The argument for it is that each worktree is a throwaway copy. That holds for files, not for anything an agent can reach from a shell, so turn it off for repositories with deploy keys or production credentials nearby. To change it later, open Settings, Agents and pick Ask for approval under Agent Permissions; Full access is the Yolo setting.
The onboarding is four screens long, and only the first one changes how agents behave:
- Pick the default agent and set Yolo mode.
- Choose a theme.
- Install or skip the GitHub CLI for issue and PR tasks.
- Test a notification, then click Add your first project.
Add a project offers Browse folder, which opens the system file picker. Before you point it anywhere, create the small demo repo this guide uses so every later command works as written. It needs git and pytest, and the repo-local identity is there because git commit refuses to run without one (use your own name and email). On Fedora, install the same two packages with sudo dnf install -y git python3-pytest; the lab only ran the Ubuntu line:
sudo apt install -y git python3-pytest
mkdir -p ~/projects/slugkit && cd ~/projects/slugkit
git init -b main
git config user.name "Joshua"
git config user.email "[email protected]"Write the three files and make the first commit, which is the base ref every Orca worktree branches from:
printf '%s\n' 'import re' '' '' 'def slugify(text):' ' text = text.strip().lower()' ' text = re.sub(r"[^a-z0-9]+", "-", text)' ' return text.strip("-")' > slugkit.py
printf '%s\n' '# slugkit' '' 'Tiny slug helper used to try Orca worktrees.' > README.md
printf '%s\n' '__pycache__/' '.pytest_cache/' > .gitignore
git add . && git commit -m "Initial slugify helper"Now register it. The CLI does the same job as Browse folder from a terminal, and it’s the quicker route when the path is already in your clipboard:
orca-ide repo add --path ~/projects/slugkitThe CLI talks to the running app, so the project appears in the sidebar straight away. Orca records it as a git project and leaves worktrees made outside Orca hidden (trimmed to the useful fields):
id: e749680e-c062-4464-b41a-51a4469664c0
path: /home/joshua/projects/slugkit
displayName: slugkit
kind: git
externalWorktreeVisibility: hideThe demo repo is a one-function Python file, slugify(), with no tests and no handling for accented characters on purpose. That’s small enough for free models to finish in under a minute, yet real enough that two agents can solve it differently, so any difference you see later comes from the agent rather than the setup. Use a repo of your own if you prefer, because nothing below depends on Python.
Check Orca’s startup log for one more line. On the lab VM it said it couldn’t tell which keyring service the desktop uses, so secrets are stored unencrypted even if a secret service is running, and suggested naming one with --password-store=gnome-libsecret (kwallet6 on KDE). The flag goes on the launch command, /opt/Orca/orca-ide --password-store=gnome-libsecret, or on the Exec= line of /usr/share/applications/orca-ide.desktop for menu launches. It only matters once you add provider accounts in Orca, but it’s easier to set before you do.
Run two coding agents side by side in worktrees
Each Orca workspace is a real git worktree with its own branch and folder, so two agents never write to the same files. In the app, click Create worktree (or press Ctrl+N), type a name and leave your default agent selected:
Orca creates the checkout under ~/orca/workspaces/<project>/<name> and names the branch after your git user.name, so the lab user Joshua got Joshua/add-tests. Name yours add-tests too, because the commands below select it by that name. Its OpenCode tab opens at an empty prompt. You can paste the prompt there, or leave it idle and let the CLI open a second OpenCode tab with the prompt already sent, which is what the lab did. Set the prompt once in your shell:
PROMPT="Add pytest tests for slugify() in tests/test_slugkit.py covering spaces, punctuation and accented input like Café Déjà Vu, run python3 -m pytest -q, and fix slugify if a test fails."Then follow these steps from any terminal on the same machine:
- Start OpenCode in the
add-testsworktree with its default free model, Big Pickle. - Create a second worktree,
add-tests-deepseek, without an agent. - Open a terminal tab in it that runs OpenCode on the free DeepSeek model.
orca-ide agent launch --agent opencode --worktree name:add-tests --surface terminal --prompt "$PROMPT"
orca-ide worktree create --repo name:slugkit --name add-tests-deepseek
orca-ide terminal create --worktree name:add-tests-deepseek --title "OpenCode DeepSeek" --command "opencode -m opencode/deepseek-v4.1-flash-free --prompt \"$PROMPT\""Step 3 looks roundabout because Orca’s own --model flag didn’t work for OpenCode in this release, as the next two errors show. Passing -m to OpenCode directly gets you the same result.
Error: “The execution host cannot verify this OpenCode model launch.”
That’s what orca-ide agent launch --agent opencode --model opencode/big-pickle returned on an existing worktree, and nothing started. The same flag on worktree create was refused before the checkout was made:
OpenCode model selection requires an existing worktree. Use --worktree current or an existing worktree selector, or omit --model.Drop --model and let OpenCode use its default, or start it through terminal create with -m as shown above. Orca’s help shows --model examples for Codex, so this looks specific to OpenCode.
Both agents finished in under a minute. The DeepSeek run added 7 tests, changed two lines of slugify() and finished in 16.1 seconds with all 7 tests passing:
Big Pickle took 39.8 seconds and wrote 9 tests, one of them for Über Straße. That test failed on its first fix, so it moved the ß replacement ahead of normalization, re-ran pytest and got 9 passed. The Source Control panel on the right shows the two changed files waiting for a commit:
Both green runs are each agent grading its own homework, though. An agent writes the tests it expects to pass, so a passing suite tells you the code matches the agent’s idea of the task, which is the whole reason to run two of them and compare.
Compare the worktrees and merge the winner
The quickest check is one awkward input run against both branches, picked from something neither agent was told about. The worktrees are plain folders, which means ordinary git and Python work on them:
cd ~/orca/workspaces/slugkit
git -C add-tests diff --stat
git -C add-tests-deepseek diff --stat
python3 -c "import sys; sys.path.insert(0,\"add-tests-deepseek\"); import slugkit; print(repr(slugkit.slugify(\"Über Straße\")))"
python3 -c "import sys; sys.path.insert(0,\"add-tests\"); import slugkit; print(repr(slugkit.slugify(\"Über Straße\")))"Both diffs touch only slugkit.py (the new test files are untracked), and the two one-liners print different slugs:
The faster agent’s version turns Ãœber Straße into uber-stra-e, because stripping combining marks does nothing for ß, which isn’t an accented letter. Its tests never tried one. Big Pickle’s branch gives uber-strasse, so that’s the one to keep. Commit it inside its worktree and fast-forward main. BRANCH picks up whatever name Orca derived from your user.name:
cd ~/orca/workspaces/slugkit/add-tests
git add -A
git commit -m "Add slugify tests and transliterate accents"
BRANCH=$(git branch --show-current)
cd ~/projects/slugkit
git merge --ff-only "$BRANCH"
python3 -m pytest -qThe merge brings in both files and the suite passes on main. Nothing from the DeepSeek branch came along, since only one branch was merged:
Updating a291083..67a3e77
Fast-forward
slugkit.py | 4 ++++
tests/test_slugkit.py | 39 +++++++++++++++++++++++++++++++++++++++
2 files changed, 43 insertions(+)
create mode 100644 tests/test_slugkit.py
9 passed in 0.02sNow remove both worktrees. Removal deletes the folder, and --force lets it go ahead when the checkout has uncommitted changes, which is what you want for the losing agent and nothing else. Orca also deletes the branch when it can tell nothing would be lost, and keeps it otherwise:
orca-ide worktree rm --worktree name:add-tests-deepseek --force
orca-ide worktree rm --worktree name:add-tests
git -C ~/projects/slugkit worktree listEach removal returns removed: true and finishes in the background. A few seconds later only the main checkout is left and git branch lists just main, so both branches went: one was merged and the DeepSeek branch never had a commit, which means its uncommitted edits are gone for good. Copy anything you want from a losing worktree before you remove it.
Worktree isolation covers files, not the machine. Both agents shared one shell environment, one ~/.config and the same network, so a worktree is not a sandbox. If you want two agents on separate kernels, Orca’s SSH targets and per-workspace cloud VMs are the next step, and the OpenCode vs Claude Code vs Cursor comparison helps decide which agent deserves the bigger box.
Run Orca headless with orca-ide serve
On a server with no desktop, orca-ide serve runs the same runtime without a window, so agents keep working after your laptop sleeps and the desktop or phone app pairs to it over a private network. It refuses to start while the desktop app owns the same profile, and in the lab it exited with code 78 and OrcadInstanceLockError until the app was closed. With the app closed, run it once with pairing off, which is a safe way to check that the server starts before you hand out a pairing link:
orca-ide serve --no-pairingThe capture below is trimmed to the lines that matter; the full log also prints [secrets], [daemon] and telemetry lines. Read the [orcad] line first, since it decides how you expose the port.
The server binds 0.0.0.0:6768, and Orca says so itself: anything that can reach the port can attempt pairing. Orca’s own remote server docs say not to forward that port to the public internet, and pair over Tailscale instead with orca-ide serve --pairing-address <tailscale-ip>, which prints the link a client pastes under Settings, Remote Orca Servers. The same docs cover running it as a systemd user service, which stops at logout unless you enable lingering with loginctl enable-linger.
Orca CLI quick reference
These are the commands this guide ran, all through the orca-ide name that Linux installs use. Apart from serve itself, each one needs the desktop app or orca-ide serve already running:
| Task | Command |
|---|---|
| Check the runtime is up | orca-ide status |
| List terminal handles | orca-ide terminal list |
| Register a repo | orca-ide repo add --path ~/projects/app |
| New worktree | orca-ide worktree create --repo name:app --name task |
| Agent in a worktree | orca-ide agent launch --agent opencode --worktree name:task --prompt "..." |
| Run any command in a tab | orca-ide terminal create --worktree name:task --command "npm test" |
| See every worktree at once | orca-ide worktree ps |
| Read an agent’s screen | orca-ide terminal read --terminal <handle> --screen |
| Delete a worktree | orca-ide worktree rm --worktree name:task |
| Headless runtime | orca-ide serve |
Telemetry is on in packaged builds and anonymous; set ORCA_TELEMETRY_DISABLED=1 (or the generic DO_NOT_TRACK=1) or switch it off under Settings, Privacy if you’d rather it didn’t phone home. For the full flag list, orca-ide <command> --help is current with whatever tag you installed, which beats any reference written against an older one, and the Orca releases page shows what changed since the release tested here.
