Orca auf einem VPS selbst hosten: Schritt-für-Schritt-Anleitung

Kurz gesagt. Orca (stablyai/orca) ist eine quelloffene Agentic Development Environment (ADE), die parallele Coding-Agenten in isolierten Git-Worktrees aus einer einzigen Oberfläche heraus ausführt. Das Setup auf einem headless Ubuntu-VPS dauert unter 20 Minuten – du brauchst das offizielle AppImage und orca serve. Einstieg für ein Zwei- oder Drei-Agenten-Fleet: Core VPS 6 (6 vCPU, 12 GB RAM). Für vier oder mehr parallele Agenten empfiehlt sich der Core VPS 8 (8 vCPU, 24 GB RAM).

Orca ist eine selbst gehostete KI-Agent-Runtime von stablyai. Auf einem VPS betrieben bekommst du persistente Agenten-Sessions, keine lokalen Rechenkosten und eine serverseitige Umgebung, auf die sich dein Desktop oder Mobilgerät von überall verbinden kann.

Voraussetzungen

Orca als selbst gehostete KI-Agent-Runtime braucht einen VPS mit ausreichend RAM und eine headless-fähige Linux-Umgebung. Sorge dafür, dass folgendes bereitsteht:

• Einen Contabo Core VPS 6 oder höher (Größenorientierung in Schritt 1). Die folgenden Befehle sind auf Ubuntu 22.04 LTS getestet. Ubuntu-24.04-Nutzer: Lies den Hinweis in Schritt 2 zu den abweichenden Paketnamen.
• Root-SSH-Zugang zum Server.
• Mindestens ein Agenten-Abo, das du in Orca einbringst – z. B. Claude Code, Codex oder OpenCode. Orca enthält keinen eigenen Agenten und berechnet auch keinen.
• Eine Domain, wenn du HTTPS-Zugang über einen Reverse Proxy willst (optional, für alles jenseits eines lokalen Tests empfohlen).

Orca hat kein eigenes Account-System und kein Login. Deine bestehenden Agenten-Abos sind die Credentials, die es verwendet.

Schritt 1: Deinen Contabo VPS bereitstellen

Orcas Ressourcenbedarf wächst mit der Anzahl der Agenten, die du parallel betreiben willst. Jeder Agent hält einen Git-Worktree offen und führt eine Terminal-Session mit einem aktiven Claude-Code- oder Codex-Prozess aus. Eine praktische Faustregel: Plane etwa 4 GB RAM pro parallelem Agenten, plus 4 GB Basis für das OS, Xvfb und die Orca-Runtime selbst.

Für die Orca ADE auf einem VPS decken diese Contabo-Pläne die häufigsten Anwendungsfälle ab:

So bereitest du deinen Server vor:

• Geh auf contabo.com und wähle den Cloud VPS-Plan, der zu deiner Arbeitslast passt.
• Wähle Ubuntu 22.04 LTS als Betriebssystem.
• Suche ein Rechenzentrum in der Nähe deines Teams. EU-Rechenzentren (Deutschland, Niederlande) halten deinen Code und deine Prompts in EU-Infrastruktur.
• Schließe die Bestellung ab. Dein Server ist in der Regel innerhalb weniger Minuten verfügbar.
• Verbinde dich per SSH: ssh root@<deine-server-ip>

Schritt 2: Die Orca-Runtime installieren

Orca wird als eigenständiges Linux-AppImage ausgeliefert. Für den Betrieb als selbst gehostete KI-Agent-Runtime auf einem headless VPS brauchst du libfuse2 (erforderlich für AppImage), xvfb-run (der Wrapper, der für jeden Befehl ein virtuelles Display startet) sowie GTK- und Electron-Laufzeitbibliotheken, die ein minimales Ubuntu-Server-Image nicht standardmäßig enthält.

Installiere alle Abhängigkeiten und lade dann das AppImage herunter:

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-Nutzer: libfuse2 wurde in 24.04 in libfuse2t64 und libasound2 in libasound2t64 umbenannt. Der obige Befehl verwendet bereits die 24.04-Namen. Auf Ubuntu 22.04 ersetzt du libfuse2t64 durch libfuse2 und libasound2t64 durch libasound2.

Prüfe, ob das Binary ausführbar ist, bevor du weitermachst:

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

Du solltest einen Orca-Versionsstring sehen. Bekommst du einen libfuse.so.2: cannot open shared object file-Fehler, prüfe, ob das richtige libfuse-Paket für deine Ubuntu-Version installiert ist. Bei libatk-1.0.so.0: cannot open shared object file führe den vollständigen apt-get install-Block oben erneut aus.

Schritt 3: Service-User anlegen und Vordergrundtest ausführen

Lege den dedizierten Non-Root-Service-User an, bevor du irgendeinen Test startest. Electron verweigert den Start als Root ohne --no-sandbox, und der Service-User muss das Orca-Verzeichnis besitzen, bevor die systemd-Unit ihn ausführt:

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

Starte jetzt orca serve im Vordergrund als orca-User, um zu bestätigen, dass die Runtime sauber startet, und um die Pairing-URL abzurufen. Der xvfb-run-Wrapper startet automatisch ein virtuelles Display. Orca startet Xvfb auf einem headless VPS nicht von selbst:

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

Das Terminal gibt einen Runtime-Endpoint und eine Pairing-URL aus. Öffne die Pairing-URL in deiner Desktop-Orca-App (Datei > Mit Remote verbinden) oder scanne sie mit der Orca-Mobile-App, um deine lokale Session mit der VPS-Runtime zu verknüpfen. Stoppe den Vordergrundprozess mit Ctrl+C, sobald du die Verbindung bestätigt hast.

Wenn Clients den Server über ein privates Netzwerk oder Tailscale erreichen, ergänze --pairing-address mit der Adresse, die sie verwenden sollen:

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'

Ersetze 100.64.1.20 durch die LAN-IP, Tailscale-IP oder den öffentlichen Hostnamen deines Servers.

Schritt 4: Die Agent-Runtime als persistenten Dienst starten

orca serve als systemd-Dienst zu betreiben hält deine selbst gehostete KI-Agent-Runtime durch SSH-Trennungen und Reboots am Leben. Der Service-User wurde bereits in Schritt 3 angelegt. Schreibe jetzt die 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 startet ein virtuelles Display und setzt DISPLAY automatisch. Füge keine zusätzliche DISPLAY=-Umgebungsvariable hinzu – das würde zu einem Konflikt führen. Ersetze YOUR_SERVER_IP durch die Adresse, die Clients verwenden werden. Aktiviere und starte den Dienst:

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

Der Journal-Output sollte den Runtime-Endpoint und die Pairing-URL anzeigen. Schlägt der Dienst sofort fehl, lies die Fehlermeldung im Journal. Der Abschnitt Fehlerbehebung weiter unten deckt die häufigsten Ursachen ab.

Schritt 5: Dein Agenten-Fleet konfigurieren

Mit laufendem orca serve verbindest du deine Desktop-Orca-App mit dem VPS:

• Öffne Orca auf deinem Desktop oder Laptop.
• Geh zu Datei > Mit Remote verbinden und gib die Pairing-URL aus dem Journal-Output ein, oder scanne sie mit der Orca-Mobile-App.
• Sobald die Verbindung steht, erstellst du einen neuen Worktree: Klicke auf New Worktree, wähle ein Repository und einen Agenten (Claude Code, Codex oder einen anderen unterstützten CLI-Agenten).
• Der Agentenprozess läuft auf dem VPS in diesem Worktree. Deine Desktop-App ist die Oberfläche. Die gesamte Rechenarbeit findet auf dem Server statt.
• Um parallele Agenten zu betreiben, erstellst du weitere Worktrees auf demselben oder auf anderen Repositories. Jeder bekommt seinen eigenen isolierten Git-Worktree und eine eigene Terminal-Session.

Die Orca-Mobile-Companion-App (iOS und Android) lässt dich Agentenstatus überwachen und Folgeanweisungen vom Smartphone senden, während die Orca ADE die eigentliche Arbeit auf dem VPS erledigt.

Optional: Reverse Proxy einrichten

Standardmäßig lauscht orca serve auf Port 6768 ohne TLS. Eine selbst gehostete KI-Agent-Runtime ohne TLS auf einer öffentlichen IP zu betreiben ist keine gute Idee. Schalte Nginx davor und hol dir ein Zertifikat von Certbot:

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

Lege eine Site-Konfiguration an:

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

Nach dem Certbot-Durchlauf ist deine Orca-Runtime unter https://orca.yourdomain.com mit einem gültigen TLS-Zertifikat erreichbar. Aktualisiere die Pairing-Adresse in der systemd-Service-Unit entsprechend.

Fehlerbehebung: Häufige Probleme

Falls deine selbst gehostete KI-Agent-Runtime oder die Orca ADE nicht startet oder Agenten sich nicht verbinden können, geh diese häufigen Ursachen durch:

• dlopen(): error loading libfuse.so.2: Das korrekte libfuse-Paket für deine Ubuntu-Version ist nicht installiert. Auf Ubuntu 22.04: sudo apt-get install -y libfuse2. Auf Ubuntu 24.04: sudo apt-get install -y libfuse2t64.
• Missing X server or $DISPLAY: Orca startet Xvfb auf einem headless VPS nicht automatisch. Verwende xvfb-run --auto-servernum wie in den Schritten 3 und 4 gezeigt. Fehlt xvfb-run selbst, installiere es mit sudo apt-get install -y xvfb.
• libatk-1.0.so.0: cannot open shared object file (oder ähnliche GTK/Electron-Bibliotheksfehler): Die vollständigen GTK- und Electron-Laufzeitabhängigkeiten aus Schritt 2 wurden nicht installiert. Führe den vollständigen apt-get install-Block aus Schritt 2 erneut aus.
• Out of memory / Agent stürzt mitten in der Aufgabe ab: Der RAM deines Plans reicht für die Anzahl paralleler Agenten nicht aus. Prüfe den freien Speicher mit free -h während Agenten laufen. Wechsle zum Core VPS 8 oder höher, wenn 12 GB dauerhaft voll sind.
• Port-Konflikt auf 6768: Ein anderer Prozess nutzt den Port. Führe sudo ss -tlnp | grep 6768 aus, um ihn zu identifizieren, oder ändere das --port-Flag in der Service-Unit auf einen freien Port.
• API-Key-Fehler von einem Agenten: Orca reicht deine bestehenden Agenten-Credentials durch. Authentifiziere dich mit dem Agenten-CLI direkt auf dem VPS erneut (z. B. claude auth login), während du als orca-Service-User eingeloggt bist: sudo -u orca claude auth login.
• Clients können sich nicht verbinden: Bestätige, dass Port 6768 in der Contabo-Firewall (oder im OS-Level-ufw) offen ist und dass --pairing-address mit der Adresse übereinstimmt, die Clients verwenden.

FAQ: Orca selbst hosten