SSH-Ausführungs-Backends

Standardmäßig führt ein Runner jede beanspruchte Aufgabe in einem Container auf seinem eigenen lokalen Docker-Host aus (SUPACLOUD_RUNNER_EXECUTION_BACKEND=docker). ADR 0046 Phase 3 ergänzt zwei SSH-Ausführungs-Backends, sodass ein Runner stattdessen einen entfernten Host ansteuern kann. Wähle ein Backend mit SUPACLOUD_RUNNER_EXECUTION_BACKEND:

Wert	Funktion	Isolation	Status
docker	Lokaler Docker-Host (Standard).	Volle Container-Caps.	GA
ssh-docker	Entfernter Docker-Daemon über SSH.	Voll — identische Container-Caps auf dem entfernten Host.	Experimentell (siehe Vorbehalte)
raw-ssh-exec	Agent als roher entfernter Prozess über SSH.	Keine — kein Container, keine Ressourcen-Limits.	Experimentell, doppelt abgesichert

Die SSH-Backends sind experimentell

Das Backend-Trait, die Auswahl, die fail-closed Boot-Guards, die Host-Key-Policy und das Command-Escaping sind produktiv verdrahtet und unit-getestet. Die Live-Remote-Läufe werden nicht in der CI geprüft (im Test-Image gibt es keinen SSH-Server), und das ssh-docker-Live-Event-Relay ist eine bekannte Lücke. Behandle beide SSH-Backends als experimentell und validiere sie gegen deinen eigenen Host, bevor du dich darauf verlässt. Sie benötigen ein Server-Binary, das mit dem ssh-backends-Cargo-Feature gebaut wurde.

Empfohlen: ssh-docker (entferntes Docker, Isolation bleibt erhalten)

Ein auf einen entfernten Daemon gerichteter DockerManager lässt dieses Backend jede Aufgabe über denselben Code-Pfad wie ein lokaler Lauf ausführen — also bleiben cap_drop=ALL, no-new-privileges, ein read-only Rootfs, tmpfs-Mounts und die Memory-/CPU-/pids-Limits auf dem entfernten Host erhalten.

1. Installiere einen SSH-Client auf dem Runner-Host. bollards SSH-Transport ruft das System-ssh-Binary auf (docker system dial-stdio). Das SupaCloud-Server-Image bringt openssh-client mit; ein eigenes Runner-Image möglicherweise nicht — installiere es (apt-get install -y openssh-client), sonst kann das Backend nicht verbinden.

2. Konfiguriere die Host-Key-Prüfung in deinem System-ssh-Client (Pflicht). Bei ssh-docker kann SupaCloud den Host-Key nicht selbst erzwingen — bollards SSH-Transport ruft das System-ssh-Binary auf und bietet nur einen Schlüsselpfad, keine -o-Optionen. Du musst diesen Client so konfigurieren, dass er den Host pinnt, und die Delegation anschließend bestätigen. Trage den Host-Key in eine known_hosts-Datei ein und richte das ssh des Runners mit strikter Prüfung darauf aus, z. B. in der ~/.ssh/config des Runner-Users:

   Host remote-host.example
     StrictHostKeyChecking yes
     UserKnownHostsFile /etc/supacloud/known_hosts

   Setze dann die Backend-Env inklusive der expliziten Delegations-Bestätigung:

   SUPACLOUD_RUNNER_EXECUTION_BACKEND=ssh-docker
   SUPACLOUD_SSH_HOST=ssh://docker@remote-host.example:22
   SUPACLOUD_SSH_KEY_PATH=/etc/supacloud/id_ed25519
   SUPACLOUD_SSH_KNOWN_HOSTS=/etc/supacloud/known_hosts
   SUPACLOUD_SSH_DOCKER_HOSTKEY_DELEGATED=true

   Der Runner startet nur, wenn beides gesetzt ist: SUPACLOUD_SSH_KNOWN_HOSTS (vorhanden, nicht leer) und SUPACLOUD_SSH_DOCKER_HOSTKEY_DELEGATED=true.

ssh-docker delegiert die Host-Key-Prüfung — du musst sie verdrahten

SupaCloud kann den Host-Key bei ssh-docker nicht prüfen (bollard reicht weder -o StrictHostKeyChecking noch UserKnownHostsFile durch). Die Prüfung läuft vollständig im System-ssh-Client, dessen Default accept-new ist (stilles Trust-on-first-use). SUPACLOUD_SSH_KNOWN_HOSTS wird nur auf Existenz geprüft — es wird nicht in die Verbindung eingespeist. Du musst StrictHostKeyChecking=yes + UserKnownHostsFile=<diese Datei> in der Config des gestarteten ssh setzen und danach SUPACLOUD_SSH_DOCKER_HOSTKEY_DELEGATED=true setzen, um zu bestätigen, dass du das getan hast. Ohne diese Verdrahtung kann ein Angreifer den Kanal mit dem Runner-Token und den Per-Run-Secrets per MITM übernehmen. (Du willst stattdessen In-Code-Host-Key-Prüfung? Nutze raw-ssh-exec, das mit russh direkt prüft — auf Kosten der Container-Isolation.)

Bekannte Lücken (ssh-docker)

• Live-Event-Relay. Die Agent-Bridge ist nur im Agent-Netz des entfernten Hosts erreichbar, sodass der Live-UI-Fortschritt einen ssh -L-Forward benötigt, den v1 nicht einrichtet. Der Lauf meldet done/failed weiterhin korrekt — nur der Live-Stream fehlt.
• Der Live-Round-Trip ist nicht in der CI. Es gibt im Test-Image keinen entfernten Docker-Daemon (und kein System-ssh), daher wird der End-to-End-Remote-Lauf nur durch einen umgebungsgesteuerten Test geprüft (SUPACLOUD_TEST_SSH_DOCKER_HOST).

raw-ssh-exec (nicht sandboxed, doppelt abgesichert)

Dieses Backend führt den Agenten als rohen entfernten Prozess aus — kein Container, keine Ressourcen-Limits, kein Event-Relay. Es existiert nur, um die ADR-0046-Entscheidung zu erfüllen, beide SSH-Varianten auszuliefern. Bevorzuge ssh-docker, sofern du es nicht ausdrücklich brauchst.

Es ist doppelt abgesichert — beide Opt-ins sind erforderlich, sonst schlägt es fail-closed fehl:

1. GATE 1 (Runner-Boot): SUPACLOUD_RUNNER_ALLOW_UNSANDBOXED=true. Dieses Backend ohne dieses Flag zu wählen ist ein harter Boot-Fehler.
2. GATE 2 (Dispatch): der Runner muss bei der Registrierung capabilities.backends: ["ssh-exec"] annoncieren und die Aufgabe muss zum ssh-exec-Backend aufgelöst werden. Eine Standardaufgabe (docker) landet nie auf einem reinen ssh-exec-Runner, und eine ssh-exec-Aufgabe nie auf einem reinen docker-Runner.

Da das Work-Payload keinen Agent-Entrypoint trägt (der normalerweise im Container-Image liegt), musst du ein kuratiertes Startkommando angeben:

SUPACLOUD_RUNNER_EXECUTION_BACKEND=raw-ssh-exec
SUPACLOUD_RUNNER_ALLOW_UNSANDBOXED=true
SUPACLOUD_SSH_HOST=ssh://agent@remote-host.example:22
SUPACLOUD_SSH_KEY_PATH=/etc/supacloud/id_ed25519
SUPACLOUD_SSH_KNOWN_HOSTS=/etc/supacloud/known_hosts
SUPACLOUD_SSH_EXEC_AGENT_CMD="run-agent --image {image} --type {agent_type}"

{image} und {agent_type} werden shell-quoted eingesetzt, und die Umgebung der Aufgabe wird über ein quoted Prolog exportiert — jeder Wert gilt als nicht vertrauenswürdig und wird escaped, sodass ein bösartiger Image-Name oder Env-Wert kein Kommando einschleusen kann.

Host-Key-Prüfung (raw-ssh-exec)

Anders als ssh-docker nutzt dieses Backend den reinen Rust-Client russh, sodass SupaCloud die Host-Key-Prüfung im eigenen Code gegen deine gepinnte SUPACLOUD_SSH_KNOWN_HOSTS durchführt: ein unbekannter oder abweichender Schlüssel wird abgelehnt (kein TOFU). Der einzige Ausweg ist SUPACLOUD_SSH_INSECURE_HOST_KEY=true, das jeden Serverschlüssel akzeptiert und eine laute Warnung loggt — niemals in einem nicht vertrauenswürdigen Netz nutzen.