Selbst gehosteter Runner

Ein selbst gehosteter Runner ist ein kleiner Agent, subaya-runner, der Subaya-Builds auf einem Rechner ausführt, den Sie kontrollieren, statt in der Subaya-Cloud. Nutzen Sie ihn, wenn die Toolchain auf diesem Rechner bereits installiert ist — etwa eine lizenzierte Quartus-Installation — oder wenn der Build auf Ihrer eigenen Hardware stattfinden muss.

Der Runner verbindet sich ausgehend über einen sicheren WebSocket mit Subaya. Er benötigt keinen eingehenden Port, kein VPN und keine öffentliche IP. Subaya schickt ihm Builds über diese Verbindung.

Ein Runner führt Builds für seine eigene Organisation aus, mit Befehlen, die die Plattform aus dem Projekt dieser Organisation abgeleitet hat. Ein Build läuft mit den Rechten des Runners auf einem Rechner, der Ihnen gehört — dasselbe Vertrauensmodell wie bei einem selbst gehosteten GitHub-Runner. Er ist keine Sandbox.

Voraussetzungen

• Linux auf x86_64. Weitere Plattformen folgen später.
• Ausgehendes HTTPS (Port 443) zu subaya-dev.com.
• Die Tools, die Ihre Builds benötigen, installiert und im PATH des Benutzers, der den Runner ausführt. Der Runner meldet, was er findet; er installiert nichts.
• Optional: Docker oder Podman für Builds, deren Rezept ein Container-Image angibt.

Installation

Öffnen Sie in der Konsole Settings → Runners und wählen Sie Add runner. Geben Sie dem Runner einen Namen; Subaya zeigt dann drei Befehle an, in die bereits ein einmaliges Registrierungstoken eingesetzt ist. Das Token funktioniert einmal und läuft nach 1 Stunde ab.

Laden Sie den Runner herunter und entpacken Sie ihn:

curl -fsSL -o subaya-runner.tar.gz https://subaya-dev.com/cli/runner/latest/subaya-runner_linux_amd64.tar.gz && tar xzf subaya-runner.tar.gz

Konfigurieren Sie ihn. Dabei wird das Registrierungstoken gegen die eigenen Zugangsdaten des Runners getauscht und ein Schlüsselpaar erzeugt, das den Rechner nie verlässt:

./subaya-runner configure --url https://subaya-dev.com --token srt_... --name 'lab-quartus-01'

Führen Sie ihn im Vordergrund aus:

./subaya-runner run

Damit er auch nach Neustarts weiterläuft, installieren Sie ihn stattdessen als systemd-Dienst:

./subaya-runner install-service

Als eigener Benutzer ausgeführt, wird ein systemd-Benutzerdienst installiert; als root ein systemweiter Dienst. Ein Benutzerdienst stoppt beim Abmelden, sofern für Ihr Konto kein Lingering aktiviert ist:

sudo loginctl enable-linger "$USER"

Nach wenigen Sekunden erscheint der Runner unter Settings → Runners als online, zusammen mit den erkannten Tools und Versionen.

Einen Build an den Runner senden

Steuern Sie einen Runner mit --runner über seinen Namen an:

suya build <app> --source . --runner lab-quartus-01 --wait

Subaya prüft vor der Annahme des Builds, ob der Runner jedes benötigte Tool gemeldet hat. Ist der Runner offline, wartet der Build in der Warteschlange und startet, sobald sich der Runner wieder verbindet.

Was aufgezeichnet wird

Beim Start eines Builds meldet der Runner die exakt gemessene Toolchain: für jedes Tool den Versionsstring, den Pfad und den SHA-256 der Binärdatei. Diese gemessene Toolchain — nicht die vom Projekt angeforderte — wird für den Lauf aufgezeichnet.

Wenn das Projekt eine Tool-Version explizit festlegt (zum Beispiel mit suya tools set quartus-pro 26.1.1) und die auf dem Runner installierte Version nicht dazu passt, wird der Build abgelehnt und schlägt mit toolchain_pin_mismatch fehl. Es wird nichts ausgeführt. Ohne explizite Festlegung wird die auf dem Runner installierte Version verwendet.

Einen Runner widerrufen

Wählen Sie unter Settings → Runners beim Runner Revoke. Der Widerruf wirkt sofort: Die Zugangsdaten des Runners funktionieren nicht mehr, seine Verbindung wird getrennt, es werden keine weiteren Builds an ihn gesendet, und ein laufender Build schlägt fehl. Ein Widerruf lässt sich nicht rückgängig machen — um den Rechner erneut zu nutzen, fügen Sie ihn als neuen Runner hinzu und führen Sie ./subaya-runner configure --replace mit dem neuen Token aus.

So entfernen Sie auch den Dienst vom Rechner:

./subaya-runner uninstall-service

Fehlerbehebung

Der Runner wird als offline angezeigt. Prüfen Sie, ob der Prozess oder Dienst läuft und ob der Rechner subaya-dev.com auf Port 443 erreicht:

./subaya-runner status

Der Runner verbindet sich nach einem Netzwerkausfall selbstständig neu. Ein Build, der beim Verbindungsabbruch lief, schlägt mit runner_disconnected fehl; starten Sie ihn erneut.

Der Runner beendet sich mit „upgrade required“. Der Runner ist älter als die Mindestversion, die Subaya akzeptiert. Laden Sie mit dem obigen Download-Befehl die neueste Version herunter, ersetzen Sie die Binärdatei und starten Sie ihn erneut. Die Konfiguration bleibt erhalten.

Der Build wird mit 422 runner_missing_tool abgelehnt. Der Runner hat ein benötigtes Tool nicht gemeldet. Installieren Sie das Tool, stellen Sie sicher, dass es im PATH des Runners liegt, und starten Sie den Runner neu, damit er seine Toolchain erneut meldet. Die Fehlermeldung nennt das fehlende Tool.

Das Registrierungstoken wird abgelehnt. Tokens sind einmalig und laufen nach einer Stunde ab. Erstellen Sie mit Add runner ein neues.

Nächste Schritte

• Workspaces & Projekte — wo Builds leben.
• Abrechnung & Nutzung — wie Cloud-Rechenzeit abgerechnet wird.