AgentVera Runner: Einrichtungsanleitung

Was Runner macht

Nutze Runner, wenn Agents auf einem leistungsstarken, immer eingeschalteten Server statt auf deinem Laptop laufen sollen. Runner hält die Terminalsitzungen der Agents auf diesem Server; klappst du den Deckel zu, bricht deine Verbindung ab oder verbindest du dich von einem anderen Computer, läuft die Sitzung weiter.

• Code und Unterhaltungen bleiben auf deinem Server.
• Die Verbindung wird über den AgentVera-Server per verschlüsseltem TLS weitergeleitet; der weitergeleitete Terminalverkehr wird dort nicht interpretiert, protokolliert oder gespeichert.
• Du siehst CPU-, Arbeitsspeicher- und Festplattenauslastung des Servers, offene Sitzungen und die Dateien in den Ordnern, die du freigibst.
• Bei Aufgaben, die von Webhooks oder „Ajana gönder“ (Send to agent) im Web kommen, wird das Ende der Ausgabe des Agents (bis zu 6.000 Zeichen) als Aufgabenzusammenfassung an den Server gemeldet, wenn sein Turn endet.

Voraussetzungen

• Ein Server oder Computer mit Linux oder macOS.
• Node.js 20 oder neuer und npm.
• curl oder wget.
• Für Agent-Sitzungen eine auf diesem Server installierte und angemeldete CLI: Claude Code, Codex, Gemini CLI oder opencode. Terminalsitzungen funktionieren immer.
• Eine AgentVera-Organisation im Tarif Pro oder Team.

Fehlt Node.js, installiere es von nodejs.org oder mit fnm:

curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22

So installierst du Claude Code und meldest dich einmal an:

npm install -g @anthropic-ai/claude-code
claude login

Installation

1. Öffne app.agentvera.dev/runners im Browser und klicke auf „Yeni runner ekle“ (Runner hinzufügen). Ein 8-stelliger Kopplungscode erscheint; er ist 10 Minuten gültig.
2. Führe den folgenden Befehl auf deinem Server aus und ersetze KOD durch deinen Kopplungscode.
3. Innerhalb weniger Sekunden erscheint der Runner auf /runners als online. Öffne ihn, um CPU-, Arbeitsspeicher- und Festplattenauslastung zu sehen, und starte mit „Yeni ajan“ (neuer Agent) eine Claude-, Codex- oder Terminalsitzung.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD

Ist der Kopplungscode abgelaufen, erstelle einfach auf /runners einen neuen.

Installer-Optionen

Füge dem Installationsbefehl diese Optionen hinzu:

• --name NAME: der Name des Runners. Standard ist der Hostname der Maschine.
• --server URL: der AgentVera-Server. Standard ist https://app.agentvera.dev.
• --no-service: keinen Hintergrunddienst installieren, falls du den Runner nur über SSH aus der Desktop-App nutzt.

curl -fsSL https://app.agentvera.dev/runner/install.sh | sh -s -- --pair KOD --name build-server

Was der Installer macht

• Installiert Runner nach ~/.agentvera-runner/app (ein Ordner, den nur du öffnen kannst) und verlinkt den Befehl als ~/.local/bin/agentvera-runner.
• Legt unter Linux mit systemd einen Benutzerdienst namens agentvera-runner an, der sich selbst neu startet, wenn er stoppt.
• Ohne systemd startet Runner im Hintergrund und schreibt ein Log nach ~/.agentvera-runner/runner.log; nach einem Neustart des Servers startest du ihn von Hand erneut.
• Installiert unter macOS einen launchd-Agent namens dev.agentvera.runner, der beim Anmelden startet, bei einem Stopp neu startet und nach ~/.agentvera-runner/runner.log protokolliert.
• Speichert das Zugriffstoken in einer Datei, die nur du lesen kannst.

Damit Runner unter Linux auch nach dem Abmelden weiterläuft, führe einmal Folgendes aus:

sudo loginctl enable-linger $USER

Kommandozeile

agentvera-runner status               # Version, Dienst, Kopplung, Server und erlaubte Ordner
agentvera-runner roots ~/projects      # Agents und Dateizugriff auf diese Ordner beschränken
agentvera-runner pair KOD --name NAME  # erneut koppeln
agentvera-runner daemon                # Runner im Vordergrund ausführen

Ohne roots arbeiten Agents in deinem Home-Ordner. Starte den Dienst nach einer erneuten Kopplung neu; Runner verbindet sich beim Start.

Den Dienst verwalten

Linux (systemd):

systemctl --user status agentvera-runner
systemctl --user restart agentvera-runner
systemctl --user stop agentvera-runner
journalctl --user -u agentvera-runner -f

macOS (launchd):

launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist   # stop
launchctl load -w ~/Library/LaunchAgents/dev.agentvera.runner.plist   # start
tail -f ~/.agentvera-runner/runner.log

Aus der Desktop-App verbinden

Die Runner-Seite in der AgentVera-Desktop-App verbindet sich auf zwei Wegen mit Runnern: über die Cloud mit demselben Konto oder direkt über einen gespeicherten SSH-Server. Wenn du SSH nutzt, kannst du mit --no-service installieren; die App startet Runner selbst, sobald sie sich verbindet.

Deinstallation

1. Lösche den Runner auf app.agentvera.dev/runners. Sein Token wird sofort widerrufen und er verbindet sich nicht mehr neu.
2. Stoppe und entferne den Dienst.
3. Lösche die Dateien von Runner.

# Linux
systemctl --user disable --now agentvera-runner
rm ~/.config/systemd/user/agentvera-runner.service

# macOS
launchctl unload ~/Library/LaunchAgents/dev.agentvera.runner.plist
rm ~/Library/LaunchAgents/dev.agentvera.runner.plist

# both
rm -rf ~/.agentvera-runner ~/.local/bin/agentvera-runner

Sicherheit

• Runner öffnet nur ausgehende Verbindungen; du musst keine Ports öffnen oder die Firewall ändern.
• Nur aktive Mitglieder deiner Organisation können den Runner sehen und sich mit ihm verbinden. Support-Mitarbeitende, die als Benutzer mitschauen, können sich nicht verbinden.
• Offene Verbindungen werden für Benutzer geschlossen, deren Mitgliedschaft endet oder deren Organisation gesperrt wird.
• Lege mit roots fest, auf welche Ordner Agents und Dateizugriff beschränkt sind.
• Per Webhook ausgelöste Aufgaben können Prompts an den Runner senden; verbinde nur Quellen, denen du vertraust.

Fehlerbehebung

• „Node.js 20 ya da üstü gerekli“ (Node.js 20 oder neuer erforderlich): Installiere Node.js 22 und führe den Befehl erneut aus.
• Ungültiger Kopplungscode: Die 10 Minuten sind möglicherweise abgelaufen; hol dir auf /runners einen neuen Code.
• Runner erscheint nicht als online: Prüfe die Ausgabe von agentvera-runner status und die Logs; stelle sicher, dass der Server app.agentvera.dev:443 erreichen kann.
• Unter „Yeni ajan“ fehlt ein Agent-Typ: Installiere diese CLI auf dem Server und melde dich an; Runner listet nur Agents auf, die er installiert vorfindet.