Run Orca's agents on a remote server

Set up the VM#

On your computer, create a VM and connect once, which also saves its host key for Orca. Pick any free name; if you've already clicked Deploy or have a VM, skip the first command and use its name:

ssh exe.dev new --name=my-orca
ssh my-orca.exe.xyz

On the VM, connect Claude Code and Codex to the LLM integration, tell Git who you are, and make a project for Orca's worktrees, a Git repository with a first commit:

exeuntu configure claude
exeuntu configure codex
git config --global user.name "Your Name"
git config --global user.email you@example.com
git init ~/project
git -C ~/project commit --allow-empty -m "Start"

Important

Do this before Orca first connects. Orca adds its own hooks to ~/.claude and ~/.codex, and exeuntu configure leaves an existing config alone.

Check that both agents answer through exe.dev:

claude -p "Reply with exactly: OK"
codex exec "Reply with exactly: OK"

Connect Orca#

On your computer, install Orca from onorca.dev or its releases. Then, in Orca:

1. Open Settings → SSH and choose Add Target. Enter host my-orca.exe.xyz, user exedev and port 22, with the SSH key you use for exe.dev (Orca also uses your SSH agent). Choose Test, then Save.

2. Add /home/exedev/project as a project, with the VM as its location. The first connection takes about 20 seconds while Orca installs its server on the VM (about 180 MB in ~/.orca-remote).

3. Create a worktree in that project, pick Claude Code or Codex, and give it a task, such as:

   Write index.html: a one-page site for a very opinionated cat. Keep it short.

The agent runs on the VM, in a new branch and folder under ~/orca/workspaces/project/. Create more worktrees for more agents; each one gets its own branch, and Orca shows their status side by side.

The first Claude Code session asks you to pick a text style and to accept Bypass Permissions mode, once. Orca starts agents with their permission prompts off (Claude Code's --dangerously-skip-permissions, Codex's --dangerously-bypass-approvals-and-sandbox), which suits a VM that holds nothing else; a worktree is a separate checkout, not a sandbox. To have agents ask first, switch Settings → Agents → Agent Permissions to Manual.

Room for more agents#

A new VM has 2 vCPUs, 8 GB of memory and a 25 GB disk, enough for a few agents. Builds, tests and dev servers in many worktrees at once need more. On your computer, give the VM more, up to your plan's capacity:

ssh exe.dev resize my-orca --cpu=8 --memory=32GB --disk=100GB

Disks can only grow. Each worktree is a full checkout with its own dependencies, so check df -h / on the VM now and then, and remove worktrees you've merged. To start big instead, pass the same flags to ssh exe.dev new.

Bring your code#

Connect a GitHub repo to the VM and it can clone, pull and push without a token or deploy key on it. On your computer, replace you/app with your repository:

ssh exe.dev integrations add github --name app --repository you/app --attach vm:my-orca

On the VM, clone it:

git clone https://github.int.exe.xyz/you/app.git ~/app

Then add /home/exedev/app as a project in Orca, the same way as ~/project. Worktree branches push to the same remote. For gh on the VM (pull requests, issues), set GH_HOST=github.int.exe.xyz; see the GitHub integration docs.

Preview what they build#

Ask an agent to serve its work on 0.0.0.0:8000, then open https://my-orca.exe.xyz/. exe.dev's HTTPS proxy serves any port from 3000 to 9999 at https://my-orca.exe.xyz:<port>/, so worktrees can each use their own port. The pages are private until you share them. Orca's Ports tab can also forward a port to your computer's localhost.

Orca in a browser#

Orca can also run as a server on the VM and serve its UI to a browser, so you can check on agents from another computer with your laptop shut. This is a separate Orca with its own projects, next to the SSH setup above.

On the VM, install the Linux package from Orca's releases (the CLI is called orca-ide on Linux; replace the version with the latest), then start the server on port 7000 (Orca's SSH server already uses 6768 on this VM):

curl -fLO https://github.com/stablyai/orca/releases/download/v1.4.245/orca-ide_1.4.245_amd64.deb
sudo apt-get install -y ./orca-ide_1.4.245_amd64.deb
orca-ide serve --port 7000 --pairing-address https://$(hostname).exe.xyz:7000

Open the Web client URL it prints in your browser. exe.dev asks you to log in, then Orca pairs the browser; if it opens unpaired, open the link again now that you're logged in. Back on the VM, press Ctrl-C and run Orca as a service that starts on boot; the browser stays paired:

orca-ide serve service install --port 7000 --pairing-address https://$(hostname).exe.xyz:7000
orca-ide serve service status
orca-ide repo add --path ~/project

Warning

The Web client URL is a lasting key to the server, and a paired browser can run any command on the VM. Keep port 7000 private.

Back up and update#

Commit and push your work from each worktree; that's the copy that matters. For a copy of the whole VM, run this on your computer:

ssh exe.dev cp my-orca my-orca-backup

Orca keeps its server on the VM in step with the desktop app. Update the agents on the VM with sudo exeuntu update claude and sudo exeuntu update codex.

Troubleshooting#

• Orca can't connect. Check that ssh my-orca.exe.xyz true works in a terminal on your computer, with the same key, and that the target's user is exedev.
• An agent asks for a login or API key. Orca connected before exeuntu configure ran, so it left Orca's config alone. On the VM, move ~/.claude/settings.json and ~/.codex/config.toml aside, run exeuntu configure claude and exeuntu configure codex, then reconnect the target in Orca.
• Claude Code exits right after starting. Its Bypass Permissions warning defaults to No, exit. Choose Yes, I accept in the terminal, once.
• The VM is slow with many agents. Check uptime and free -h on the VM, then give it more.

For everything else, see Orca's SSH docs.