How to Self-Host Orca on a VPS: Step-by-Step Setup

In short. Orca (stablyai/orca) is an open-source agentic IDE that runs parallel coding agents, each in its own git worktree, from a single interface. You can self-host Orca on a headless Ubuntu VPS in under 20 minutes using the official AppImage and orca serve. A Core VPS 6 (6 vCPU, 12 GB RAM) is the practical entry point for a two- or three-agent fleet. Upgrade to a Core VPS 8 (8 vCPU, 24 GB RAM) for four or more agents running concurrently.

Orca is a self hosted AI agent runtime built by stablyai. Run it on a VPS and you get persistent agent sessions, no local compute cost, and a server-side environment your desktop or mobile companion can connect to from anywhere.

Prerequisites

Running the Orca agentic IDE as a self hosted AI agent runtime requires a VPS with enough RAM and a headless-compatible Linux environment. Make sure you have:

• A Contabo Core VPS 6 or higher (see Step 1 for sizing guidance). The commands below are tested on Ubuntu 22.04 LTS. Ubuntu 24.04 LTS users: see the callout in Step 2 for the package names that differ.
• Root SSH access to the server.
• At least one agent subscription you will bring to Orca, such as Claude Code, Codex, or OpenCode. Orca does not include an agent, and it does not charge for one either.
• A domain name if you want HTTPS access via a reverse proxy (optional but recommended for anything beyond a local test).

Orca itself has no account system and no login. Your existing agent subscriptions are the credentials it uses.

Step 1: Provision Your Contabo VPS

Orca’s resource requirements scale with the number of agents you plan to run in parallel. Each agent holds a git worktree open and runs a terminal session with a live Claude Code or Codex process. A useful planning rule: budget roughly 4 GB RAM per concurrent agent, plus a 4 GB base for the OS, Xvfb, and the Orca runtime itself.

For the orca agentic IDE on a VPS, these Contabo plans cover the common use cases:

To provision your server:

1. Go to contabo.com and select the Cloud VPS plan that fits your workload.
2. Choose Ubuntu 22.04 LTS as the operating system.
3. Pick a data center region close to your team. EU data centers (Germany, Netherlands) keep your code and prompts in EU infrastructure.
4. Complete the order. Your server is typically available within a few minutes.
5. Connect via SSH: ssh root@<your-server-ip>

Step 2: Install the Orca Runtime

Orca ships as a self-contained Linux AppImage. Setting it up as a self hosted AI agent runtime on a headless VPS requires libfuse2 (required by AppImage), xvfb-run (the wrapper that starts a virtual display for each command), and a set of GTK and Electron runtime libraries that a minimal Ubuntu server image does not include by default.

Install all dependencies, then download the AppImage:

sudo apt-get update
sudo apt-get install -y \
  curl libfuse2 xvfb \
  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 \
  libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 \
  libpango-1.0-0 libcairo2 libgtk-3-0 libgdk-pixbuf2.0-0 \
  libnss3 libnspr4 libxss1 libxtst6 libasound2t64
sudo mkdir -p /opt/orca
sudo curl -L https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage \
  -o /opt/orca/orca-linux.AppImage
sudo chmod +x /opt/orca/orca-linux.AppImage

Ubuntu 24.04 users: libfuse2 was renamed to libfuse2t64 and libasound2 to libasound2t64 in 24.04. The command above already uses the 24.04 names. On Ubuntu 22.04, replace libfuse2t64 with libfuse2 and libasound2t64 with libasound2.

Verify the binary is executable before continuing:

/opt/orca/orca-linux.AppImage --version

You should see an Orca version string. If you get a libfuse.so.2: cannot open shared object file error, check that the correct libfuse package for your Ubuntu version is installed. If you get a libatk-1.0.so.0: cannot open shared object file error, re-run the full apt-get install block above.

Step 3: Create the Service User and Run a Foreground Test

Create the dedicated non-root service user before running any test. Electron refuses to start as root without --no-sandbox, and the service user needs to own the Orca directory before the systemd unit runs it:

sudo useradd --system --create-home --shell /usr/sbin/nologin orca
sudo chown -R orca:orca /opt/orca

Now run orca serve in the foreground as the orca user to confirm the runtime starts cleanly and to retrieve the pairing URL. The xvfb-run wrapper starts a virtual display automatically. Orca does not start Xvfb on its own on a headless VPS:

sudo -u orca sh -c 'xvfb-run --auto-servernum \
  LIBGL_ALWAYS_SOFTWARE=1 \
  /opt/orca/orca-linux.AppImage serve --port 6768'

The terminal prints a runtime endpoint and a pairing URL. Open the pairing URL on your desktop Orca app (File > Connect to Remote) or on the Orca mobile app to link your local session to the VPS runtime. Stop the foreground process with Ctrl+C once you have confirmed the connection works.

If clients will reach the server over a private network or Tailscale, add --pairing-address with the address they should use:

sudo -u orca sh -c 'xvfb-run --auto-servernum \
  LIBGL_ALWAYS_SOFTWARE=1 \
  /opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address 100.64.1.20'

Replace 100.64.1.20 with your server’s LAN IP, Tailscale IP, or public hostname.

Step 4: Start the Agent Runtime as a Persistent Service

Running orca serve as a systemd service keeps your self hosted AI agent runtime alive through SSH disconnects and reboots. The service user was already created in Step 3. Write the service unit:

sudo tee /etc/systemd/system/orca-serve.service > /dev/null << 'EOF'
[Unit]
Description=Orca runtime server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=orca
WorkingDirectory=/home/orca
Environment=LIBGL_ALWAYS_SOFTWARE=1
ExecStart=/usr/bin/xvfb-run --auto-servernum /opt/orca/orca-linux.AppImage serve --port 6768 --pairing-address YOUR_SERVER_IP
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

xvfb-run --auto-servernum starts a virtual display and sets DISPLAY automatically. Do not add a DISPLAY= environment variable line. The two would conflict. Replace YOUR_SERVER_IP with the address clients will use. Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now orca-serve.service
sudo journalctl -u orca-serve.service -f

The journal output should show the runtime endpoint and pairing URL. If the service fails immediately, check the journal for a specific error message. The Troubleshooting section below covers the most common ones.

Step 5: Configure Your Agent Fleet

With orca serve running, connect your desktop Orca app to the VPS:

1. Open Orca on your desktop or laptop.
2. Go to File > Connect to Remote and enter the pairing URL from the journal output, or scan it with the Orca mobile app.
3. Once connected, create a new worktree: click New Worktree, select a repository, and choose an agent (Claude Code, Codex, or any other supported CLI agent).
4. The agent process runs on the VPS inside that worktree. Your desktop app is the interface. All compute happens on the server.
5. To run parallel agents, create additional worktrees on the same repository or on different ones. Each gets its own isolated git worktree and terminal session.

The Orca mobile companion app (iOS and Android) lets you monitor agent status and send follow-up prompts from your phone while the orca agentic IDE handles the actual work on the VPS.

Optional: Set Up a Reverse Proxy

By default, orca serve listens on port 6768 without TLS. Exposing a self hosted AI agent runtime on a public IP without TLS is not a good idea. Put Nginx in front of it and get a certificate from Certbot:

sudo apt-get install -y nginx certbot python3-certbot-nginx

Create a site configuration:

sudo tee /etc/nginx/sites-available/orca << 'EOF'
server {
    listen 80;
    server_name orca.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:6768;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}
EOF
sudo ln -s /etc/nginx/sites-available/orca /etc/nginx/sites-enabled/
sudo nginx -t &amp;& sudo systemctl reload nginx
sudo certbot --nginx -d orca.yourdomain.com

After Certbot runs, your Orca runtime is reachable at https://orca.yourdomain.com with a valid TLS certificate. Update the pairing address in the systemd service unit to match the domain.

Troubleshooting: Common Issues

If your self hosted AI agent runtime or the Orca agentic IDE does not start, or agents fail to connect, work through these common causes:

• dlopen(): error loading libfuse.so.2: The correct libfuse package for your Ubuntu version is not installed. On Ubuntu 22.04 run sudo apt-get install -y libfuse2. On Ubuntu 24.04 run sudo apt-get install -y libfuse2t64.
• Missing X server or $DISPLAY: Orca does not start Xvfb automatically on a headless VPS. Use xvfb-run --auto-servernum as shown in Steps 3 and 4. If xvfb-run itself is missing, install it with sudo apt-get install -y xvfb.
• libatk-1.0.so.0: cannot open shared object file (or any similar GTK/Electron library error): The full set of GTK and Electron runtime dependencies from Step 2 was not installed. Re-run the full apt-get install block in Step 2.
• Out of memory / agent crashes mid-task: Your plan’s RAM is too low for the number of concurrent agents. Check free memory with free -h while agents are running. Move to a Core VPS 8 or higher if 12 GB is consistently full.
• Port conflict on 6768: Another process is using the port. Run sudo ss -tlnp | grep 6768 to identify it, or change the --port flag in the service unit to an open port.
• API key errors from an agent: Orca passes your existing agent credentials through. Re-authenticate with the agent CLI directly on the VPS (for example, claude auth login) while SSH’d in as the orca service user: sudo -u orca claude auth login.
• Clients cannot connect: Confirm port 6768 is open in the Contabo firewall (or OS-level ufw) and that --pairing-address matches the address clients are trying to reach.

FAQ: Self-Hosting Orca