Umgebungsvariablen

Dies sind die zentralen Variablen, die der SupaCloud-Server einliest. Das eigenständige Deployment setzt sie über .env (siehe Self-Hosting mit Docker Compose). Es handelt sich um eine praxistaugliche Auswahl, nicht um eine vollständige Liste.

Core

Variable	Standard	Zweck
`MODE`	—	`dev` (der Standard, wenn nicht gesetzt) lockert die ausschließlich in der Produktion geltenden Schutzmechanismen. Setze für die Produktion `MODE=prod` (oder `production`) — jeder andere Wert, auch ein nicht gesetzter, läuft im Dev-Modus.
`PUBLIC_URL`	—	Öffentliche Basis-URL des Servers. In der Produktion erforderlich.
`CORS_ALLOWED_ORIGINS`	—	Kommagetrennte Origins, die die API aufrufen dürfen.
`DATABASE_URL`	`postgresql://supacloud:supacloud@postgres:5432/supacloud`	PostgreSQL-Verbindungszeichenfolge.
`SERVER_PORT`	`8080`	Port, auf dem der Server lauscht.

Anmeldung & Secrets

Variable	Standard	Zweck
`AUTH_PROVIDER`	`builtin`	Authentifizierungsanbieter.
`SUPACLOUD_JWT_SECRET`	—	Erforderlich. Secret zum Signieren der Sitzung, ≥ 32 Byte.
`SUPACLOUD_INITIAL_ADMIN_EMAILS`	—	E-Mail-Adresse(n), die als anfänglicher Owner bereitgestellt werden. In Prod erforderlich für `builtin`/`oidc` (Boot schlägt fehl, wenn nicht gesetzt); die Beispieldateien liefern `admin@example.com` nur als Platzhalter.
`AUTH_COOKIE_SECURE`	—	`false` für lokales HTTP; `true` (Standard in der Produktion) für HTTPS.
`SECRET_BACKEND`	auto	`openbao` oder `env`. Liegt eine Vault-Authentifizierung vor, erkennt der Server OpenBao automatisch. Siehe Secret-Bereitstellung.
`SUPACLOUD_CALIBRATION_SWEEP_INTERVAL_SECS`	`86400` (1 Tag)	Wie oft die unbeaufsichtigte Modellketten-Kalibrierung entscheidet. Die Schleife fragt stündlich nach und fährt einen Lauf, sobald der letzte mindestens so alt ist; der erste Lauf kommt 30 Minuten nach dem Start, `0` schaltet ihn ab. Bei mehreren Server-Repliken fährt genau eine den Lauf, die übrigen sehen das Lease und überspringen.
`SUPACLOUD_CALIBRATION_SWEEP_MIN_AGE_SECS`	das Sweep-Intervall	Mindestalter des letzten Laufs, bevor die stündliche Abfrage einen neuen fährt. `0` heißt jede Abfrage, ein stündlicher Messmodus — bewusst und kurz setzen, die Budgets der Benchmark-Quellen sind geteilt.
`SUPACLOUD_CALIBRATION_REFRESH_INTERVAL_SECS`	`21600` (6 h)	Wie oft die Benchmark-Schnappschüsse hinter der Kalibrierung erneuert werden. Sie versorgen auch den interaktiven Kalibrieren-Knopf, deshalb erneuern sie schneller, als der Sweep entscheidet. `0` schaltet die Erneuerung ab.
`SUPACLOUD_RESOURCE_SECRET_RECONCILE_INTERVAL_SECS`	`21600` (6 h)	Wie oft der Server Ressourcen-Secrets von Workflows entfernt, die keine Ressourcen-Zeile je wieder liest, etwa nach dem Anlegen einer Ressource, deren Datenbank-Schreibvorgang scheiterte. Läuft nur mit einer OpenBao-Sitzung; der erste Durchlauf kommt 15 Minuten nach dem Start; `0` schaltet ihn ab. Ein Secret wird erst entfernt, wenn zwei Durchläufe es als unbeansprucht, nicht gelöscht und älter als 15 Minuten gefunden haben. Endgültig ist das Entfernen, wenn die OpenBao-Policy `delete` auf `supacloud/metadata/workflows/resources/*` gewährt; ohne diese Berechtigung wird das Secret nur weich gelöscht und der Server protokolliert einen Fehler.

KI & Sprache

Variable	Standard	Zweck
`GROQ_API_KEY`	—	Instanzweiter Groq-Schlüssel (Achtung: Groq, nicht Grok) für die Spracheingabe per Whisper-Transkription; aktiviert das Diktieren in der gesamten App. Die App liest ihn zuerst aus der Umgebung und – bei `SECRET_BACKEND=openbao` – anschließend aus der OpenBao-Map `supacloud/ai`.
`XAI_API_KEY`	—	Instanzweiter xAI-(Grok-)API-Schlüssel. Versorgt die Grok-Modelle (`grok-4.5`, `grok-build-0.1`, …), die über den OpenCode-Agenten angeboten werden. Schlüssel pro Nutzer/Workspace werden normalerweise unter Einstellungen → API-Schlüssel (Anbieter xAI / Grok) hinterlegt; diese Umgebungsvariable ist der instanzweite Fallback. Die App liest ihn zuerst aus der Umgebung und – bei `SECRET_BACKEND=openbao` – anschließend aus der OpenBao-Map `supacloud/ai`.

Agent-Sandbox

Variable	Standard	Zweck
`AGENT_NETWORK`	`supacloud-agents`	Docker-Netzwerk, dem Agent-Container beitreten.
`AGENT_MEMORY_BYTES`	`2147483648`	Arbeitsspeicher-Obergrenze pro Agent (Byte).
`AGENT_NANO_CPUS`	`2000000000`	CPU-Obergrenze pro Agent (Nano-CPUs).
`AGENT_PIDS_LIMIT`	`512`	PID-Limit pro Agent.
`AGENT_READ_ONLY_ROOTFS`	`true`	Das Root-Dateisystem des Agenten schreibgeschützt einbinden.
`AGENT_TMPFS_TMP_MB`	`512`	Obergrenze des `/tmp`-tmpfs im Agent-Container, in MiB.
`AGENT_TMPFS_RUN_MB`	`64`	Obergrenze des `/run`-tmpfs, in MiB.
`AGENT_TMPFS_HOME_MB`	`512`	Obergrenze von `/home/agent` — Konfiguration und Zustand der CLIs sowie der npm-Zwischenspeicher.
`SUPACLOUD_AGENT_TEST_DB`	`false`	Wand 6 Option C — Fähigkeits-Schranke der Instanz für den flüchtigen Postgres-Sidecar je Aufgabe. Ist sie aus, wird nie ein Sidecar erstellt. Ist sie an, bekommt eine Aufgabe nur dann einen Sidecar, wenn sie ihn wählt (`task.config.test_db = true`); eine nicht gewählte Aufgabe bekommt keinen. Ein explizit gesetztes `TEST_DATABASE_URL` des Aufrufers hat Vorrang: es wird nie überschrieben und der Sidecar unterdrückt. Der Sidecar injiziert `TEST_DATABASE_URL`, sein Passwort wird in den Redaktionssatz des Laufs aufgenommen, und er wird mit dem Agent-Container entfernt.
`AGENT_TEST_DB_IMAGE`	`postgres:18`	Image für den `SUPACLOUD_AGENT_TEST_DB`-Sidecar.
`ATTACHMENTS_FILE_WAIT_MS`	`30000`	Wie lange ein Agent-Container auf seine Anhang-Datei wartet. Wird IM Agent-Container gesetzt, nicht auf dem Server.
`AGENT_TASK_TIMEOUT_MINUTES`	`90`	Hartes Timeout pro Agent-Task.
`MAX_PARALLEL_TASKS_PER_WORKSPACE`	`3`	Parallelitäts-Obergrenze pro Workspace.

Die AGENT_TMPFS_*-Obergrenzen gehen von AGENT_MEMORY_BYTES ab, nicht von der Platte. Ein tmpfs liegt im Arbeitsspeicher, seine Seiten werden dem Speicher-cgroup des Containers angerechnet — wie viel Platte auf dem Host frei ist, spielt für diese drei Einhängungen keine Rolle.

Eine einzelne Obergrenze anzuheben bringt deshalb nichts. Es ändert nur die Art des Fehlers: statt eines sauberen ENOSPC („kein Speicherplatz mehr”) wird der Container per OOM beendet, was sich als Task zeigt, der ohne Erklärung stirbt. AGENT_MEMORY_BYTES gehört im selben Schritt mit angehoben. Der Server warnt beim Start, wenn die Obergrenzen zusammen das Speicherlimit übersteigen, und nennt beide Zahlen.

/workspace gehört nicht dazu. Das Arbeitsverzeichnis des Agenten — der Klon und alles, was darin gebaut wird — ist ein anonymes Docker-Volume auf echter Platte. Es zählt nicht gegen das Speicherlimit, hat deshalb auch keinen Größenknopf, und Docker löscht es zusammen mit dem Container: ein beendeter Task lässt nichts zurück. Zuvor war es ein 1-GiB-tmpfs und damit allein die Hälfte der gesamten Speicherzuteilung des Containers — ein Build, der es füllte, wurde per OOM beendet statt als „kein Platz mehr” gemeldet.

Observability

Variable	Standard	Zweck
`SUPACLOUD_GLITCHTIP_DSN`	—	DSN eines GlitchTip-Projekts (Sentry-kompatibel). Wenn gesetzt, meldet der Server gezielte Fehler-Events dorthin: operative Alert-Auslösungen (Tick-SLA, Queue-Alter, Fehler-Spike, Budget 80 %, Wochenfenster niedrig — ein Event pro Auslösung), Circuit-Breaker-Trips / Provider-Failover (gruppiert je Provider und Fehlerklasse) sowie terminal fehlgeschlagene Workflow-Läufe (mit Deep-Link auf den Lauf, gruppiert nach Workflow + Node + Fehlerklasse — ein dauerhaft fehlschlagender Intervall-Flow bleibt ein einziges Issue), dazu `error!`-Log-Events und Panics. Jede Payload wird vor dem Versand durch die Redaction-Wall des Servers geschrubbt. Nicht gesetzt ⇒ die Senke ist vollständig deaktiviert — kein Client, kein Netzwerkversuch. Auflösung env-zuerst, dann aus der OpenBao-Map `supacloud/app`.

Runner-Flotte (Hub-Modus)

Optional; standardmäßig aus. Siehe Einen Runner sicher einrichten und Runner steuern & überwachen.

Auf dem Server (Hub)

Variable	Standard	Zweck
`SUPACLOUD_HUB_MODE`	`false`	Dispatch an Remote-Runner aktivieren. Solange `false`, läuft jede Aufgabe lokal — unabhängig von registrierten Runnern.
`SUPACLOUD_HUB_EVENT_RELAY`	`false`	Echtzeit-Hub-Events über Postgres `LISTEN/NOTIFY` zwischen Server-Replicas weiterleiten, damit ein WebSocket-Client auf einer beliebigen Replica ein auf einer anderen ausgelöstes Signal erhält. Nur bei mehreren Server-Replicas aktivieren; eine einzelne Replica bleibt unberührt.
`SUPACLOUD_RUNNER_STALE_SECS`	`90`	Heartbeat-Veraltungs-Fenster, ab dem ein Runner `offline` markiert und seine nicht begonnene Arbeit erneut bereitgestellt wird. Untergrenze `45`.
`SUPACLOUD_TLS_CERT_PATH`	—	Pfad zum PEM-Server-Zertifikat. Gemeinsam mit `SUPACLOUD_TLS_KEY_PATH` setzen, um den Hub direkt über TLS auszuliefern (statt TLS an einem Proxy zu terminieren). Nur eines von beiden zu setzen ist ein harter Boot-Fehler (fail-closed). Beide ungesetzt ⇒ Klartext-HTTP genau wie heute (Byte-für-Byte identischer Standard).
`SUPACLOUD_TLS_KEY_PATH`	—	Pfad zum PEM-Private-Key, die Schlüsselhälfte von `SUPACLOUD_TLS_CERT_PATH`.
`SUPACLOUD_TLS_CLIENT_CA_PATH`	—	PEM-CA-Bundle. Ist es gesetzt (TLS muss bereits an sein), verlangt und verifiziert der Hub zusätzlich ein Client-Zertifikat bei jeder Verbindung — Mutual TLS (mTLS). Ein Runner ohne vertrauenswürdiges Client-Zertifikat wird beim Handshake abgewiesen. Dies ohne `SUPACLOUD_TLS_CERT_PATH`/`_KEY_PATH` zu setzen ist ein harter Boot-Fehler. Siehe Einen Runner sicher einrichten.

Installer-Einstiegspunkte

/install-runner.sh und /install-runner.ps1 sind die öffentlichen Einstiegspunkte, die der Web-Wizard dem Betreiber übergibt. Der Hub trägt den Installer-Body nicht selbst: er leitet um auf den veröffentlichten, gestempelten Installer im Release-Feed (runner-release.yml publiziert ihn version-keyed im öffentlichen bw-public-Package-Feed). Beide Werte sind nicht-geheim.

Variable	Standard	Zweck
`SUPACLOUD_RUNNER_VERSION`	—	Release-Version, auf die der Hub zeigt: `<download base>/<version>/install-runner.{sh,ps1}`. Erforderlich — ohne sie antworten die Einstiegspunkte `503`.
`SUPACLOUD_RUNNER_DOWNLOAD_BASE`	—	Basis-URL des Release-Feeds, z. B. `https://git.blockworx.tech/api/packages/bw-public/generic/supacloud-runner`. Erforderlich — ohne sie antworten die Einstiegspunkte `503`.

Der veröffentlichte, gestempelte Installer und die Release-Binaries kommen aus der Forgejo-Release-Pipeline (ADR 0046), nicht von diesem Server. Bis der Release-Kanal konfiguriert ist, onboarde über das Docker-Image oder ein selbstgebautes Binary.

Autoscaler (experimentell, in v1 nur lokales Docker)

Standardmäßig aus. Wenn aus, wird keine Hintergrundschleife gestartet, und das Dispatching ist unverändert. Siehe Runner steuern & überwachen.

Variable	Standard	Zweck
`SUPACLOUD_RUNNER_AUTOSCALE`	`off`	`off` oder `on`. Bei `on` betreibt der Hub eine integrierte Autoscaler-Schleife, die anhand des Fleet-Pull-Queue-Signals lokale Docker-Runner-Container startet und wieder einzieht. Standard `off` ⇒ keine Schleife, keine Verhaltensänderung.
`SUPACLOUD_RUNNER_AUTOSCALE_MIN`	—	Untergrenze der laufenden Runner-Anzahl, die der Autoscaler hält.
`SUPACLOUD_RUNNER_AUTOSCALE_MAX`	—	Obergrenze der Runner-Anzahl, die der Autoscaler starten darf.
`SUPACLOUD_RUNNER_AUTOSCALE_RUNNER_IMAGE`	—	Das Container-Image, das der Autoscaler für jeden neuen Runner startet. Erforderlich, wenn Autoscale `on` ist. Der Autoscaler braucht zudem ein Runner-Token, das er dem gestarteten Container übergibt (siehe How-to).
`SUPACLOUD_RUNNER_AUTOSCALE_COOLDOWN_SECS`	—	Mindestabstand in Sekunden zwischen Skalierungsaktionen, dämpft Flattern.
`SUPACLOUD_RUNNER_AUTOSCALE_NETWORK`	`supacloud-agents`	Docker-Netz, an das der Autoscaler jeden gestarteten Runner-Container anschließt.

Auf dem Runner (Worker-Node, `--runner`-Modus)

Variable	Standard	Zweck
`SUPACLOUD_HUB_URL`	—	Erforderlich. Die Hub-Basis-URL. Muss `https://` sein, außer das Insecure-Flag unten ist gesetzt.
`SUPACLOUD_RUNNER_TOKEN`	—	Das `scrn_…`-Bearer-Token aus einer System-Admin-Registrierung (einmalig gezeigt). Gib entweder dieses oder `SUPACLOUD_RUNNER_ENROLLMENT_TOKEN` an.
`SUPACLOUD_RUNNER_ENROLLMENT_TOKEN`	—	Das einmalige Enrollment-Token, das der Runner beim Boot selbst (über den gRPC-`ExchangeToken`-RPC) gegen ein scope-begrenztes, kurzlebiges `scrnj_…`-JWT eintauscht (und danach automatisch erneuert). Wird für das Onboarding Dritter genutzt — siehe Einen Runner sicher einrichten. Das Token ist einmalig und wird beim ersten Eintausch verbraucht; gib entweder dieses oder `SUPACLOUD_RUNNER_TOKEN` an, nie beide.
`SUPACLOUD_RUNNER_LABELS`	—	Beworbene Capability-Labels, durch Komma/Leerzeichen getrennt (klein gefaltet + dedupliziert). Werden beim Enrollment als `capabilities.labels` gesendet, sodass ein Task-`config.runner.required_labels` auf diesen Runner routen kann. Die Capabilities `backends`/`isolation` leitet der Runner aus `SUPACLOUD_RUNNER_EXECUTION_BACKEND` ab — nie hier gesetzt.
`SUPACLOUD_RUNNER_TOKEN_FILE`	`$XDG_STATE_HOME/supacloud-runner/runner-token` (Fallback `$HOME/.local/state/…`; unter Windows `%LOCALAPPDATA%\supacloud\runner-token`)	Pfad der Datei, in die der Runner sein scope-begrenztes `scrnj_…`-JWT persistiert und aus der er es beim Boot zurückliest. Das Enrollment-Token ist einmalig; ohne diese Datei stünde ein enrolter Runner nach einem Reboot ohne Credential da. Wird atomar mit Modus `0600` geschrieben und vor jedem Eintausch gelesen — eine gültige Datei bedeutet kein zweiter `ExchangeToken`. Eine abgelaufene, fehlerhafte oder für Gruppe/Andere lesbare Datei wird verworfen und der Runner enrolt neu. Die Installer setzen dies explizit (`runner-token` unter dem State-Verzeichnis des Runners — `/var/lib/supacloud-runner` als root). Für ein statisches `scrn_…`-Token ignoriert, da es nie abläuft. Siehe Einen Runner sicher einrichten.
`SUPACLOUD_RUNNER_TOKEN_REFRESH_SECS`	`0`	Nur für einen eingeschriebenen (`scrnj_…`-JWT-)Runner: wie viele Sekunden vor Ablauf das JWT neu eingetauscht wird. `0` (der Standard) leitet den Takt automatisch ab — etwa die halbe Token-TTL (aus `runners.token_expires_at` / dem JWT-`exp`) — sodass der Daemon deutlich vor Ablauf erneuert. Ein statisches `scrn_…`-Token läuft nie ab und wird nie erneuert; für dieses ist die Variable ein No-op.
`SUPACLOUD_RUNNER_NAME`	`supacloud-runner`	An den Hub gemeldeter Anzeigename (ungesetzt/leer ergibt diesen Wert).
`SUPACLOUD_RUNNER_HEARTBEAT_SECS`	`30`	Wie oft der Runner den Hub heartbeatet.
`SUPACLOUD_RUNNER_POLL_SECS`	`3`	Wie oft der Runner nach abholbarer Arbeit pollt.
`SUPACLOUD_RUNNER_ALLOW_INSECURE_TRANSPORT`	`false`	Erlaubt eine Klartext-`http://`-Hub-URL. Nur in einem vertrauenswürdigen privaten Netz — Token und laufspezifische Secrets queren diesen Kanal.
`AGENT_NETWORK`	`supacloud-agents`	Docker-Netz für Agent-Container des Runners (muss auf dem Worker existieren).
`SUPACLOUD_RUNNER_EXECUTION_BACKEND`	`docker`	Wie der Runner eine beanspruchte Aufgabe ausführt: `docker` (lokales Docker, Standard), `ssh-docker` (entferntes Docker über SSH), `raw-ssh-exec` (eingeschränkter, nicht sandboxed entfernter Prozess) oder `microvm` (stärkste Isolation — eine vom Launcher gestartete microVM pro Aufgabe). Die SSH-Backends benötigen einen mit dem `ssh-backends`-Feature gebauten Binary; `microvm` einen mit dem `microvm-backend`-Feature. Ein Backend zu wählen, dessen Feature nicht einkompiliert wurde, ist ein harter Boot-Fehler (fail-closed). Siehe SSH-Ausführungs-Backends und Einen Runner sicher einrichten.
`SUPACLOUD_RUNNER_MICROVM_CMD`	—	Nur `microvm`-Backend: das operatorseitig bereitgestellte Launcher-Kommando, das SupaCloud aufruft, um die microVM pro Aufgabe zu starten (z. B. ein Firecracker/Kata-Wrapper). Erforderlich, wenn `SUPACLOUD_RUNNER_EXECUTION_BACKEND=microvm` — das Runner-Image liefert keinen microVM-Launcher.
`SUPACLOUD_RUNNER_TLS_CLIENT_CERT_PATH`	—	Pfad zum PEM-Client-Zertifikat. Gemeinsam mit `SUPACLOUD_RUNNER_TLS_CLIENT_KEY_PATH` setzen, damit der Runner einem Hub, der mTLS verlangt, eine Client-Identität präsentiert. Nur eines von beiden zu setzen ist ein harter Boot-Fehler. Ungesetzt ⇒ heutiges One-Way-TLS-Verhalten.
`SUPACLOUD_RUNNER_TLS_CLIENT_KEY_PATH`	—	Pfad zum PEM-Private-Key, die Schlüsselhälfte von `SUPACLOUD_RUNNER_TLS_CLIENT_CERT_PATH`.
`SUPACLOUD_RUNNER_TLS_CA_PATH`	—	PEM-CA-Bundle, mit dem der Runner das Zertifikat des Hubs pinnt (statt des System-Trust-Stores). Optional; ungesetzt ⇒ heutiges Verhalten.
`SUPACLOUD_SSH_HOST`	—	`ssh://user@host:port` — der SSH-Endpunkt für beide SSH-Backends. Erforderlich für `ssh-docker`/`raw-ssh-exec`.
`SUPACLOUD_SSH_KNOWN_HOSTS`	—	Pfad zu einer gepinnten `known_hosts`-Datei. Erforderlich für beide SSH-Backends; der Runner startet nicht, wenn sie fehlt oder leer ist. Bei `raw-ssh-exec` ist dies der In-Code-Anker (`russh` weist einen unbekannten/abweichenden Key ab — kein TOFU). Bei `ssh-docker` kann SupaCloud sie nicht über bollard verdrahten — sie ist nur ein Tippfehler-Schutz; du musst deinen System-`ssh`-Client darauf ausrichten und `SUPACLOUD_SSH_DOCKER_HOSTKEY_DELEGATED` setzen.
`SUPACLOUD_SSH_DOCKER_HOSTKEY_DELEGATED`	`false`	Nur `ssh-docker` — erforderlich. Explizite Bestätigung, dass die SSH-Host-Key-Prüfung an den System-`ssh`-Client delegiert ist (SupaCloud kann den Pin nicht über bollard erzwingen). `ssh-docker` ohne dieses truthy-Flag ist ein harter Boot-Fehler — sonst würde ein unbekannter Host-Key still akzeptiert (accept-new TOFU). Setze es erst, nachdem du das ssh des Runner-Hosts mit `StrictHostKeyChecking=yes` + `UserKnownHostsFile=<SUPACLOUD_SSH_KNOWN_HOSTS>` konfiguriert hast.
`SUPACLOUD_SSH_KEY_PATH`	—	Pfad zur privaten SSH-Schlüsseldatei. Erforderlich für `raw-ssh-exec` (nur Schlüssel-Auth, kein Agent-Forwarding); optional für `ssh-docker`. Die Schlüsselbytes werden nie geloggt.
`SUPACLOUD_RUNNER_ALLOW_UNSANDBOXED`	`false`	GATE 1 für `raw-ssh-exec`. Dieses Backend ohne dieses truthy-Flag zu wählen ist ein harter Boot-Fehler — es führt den Agenten OHNE Container-Isolation und OHNE Ressourcen-Limits aus.
`SUPACLOUD_SSH_EXEC_AGENT_CMD`	—	Nur `raw-ssh-exec`: das operatorseitig kuratierte Remote-Agent-Startkommando-Template (Platzhalter `{image}`/`{agent_type}`, shell-quoted). Erforderlich — das Work-Payload trägt keinen Agent-Entrypoint.
`SUPACLOUD_SSH_INSECURE_HOST_KEY`	`false`	Nur `raw-ssh-exec`: deaktiviert die Host-Key-Prüfung (akzeptiert jeden Serverschlüssel). Der einzige Ausweg aus der fail-closed Host-Key-Prüfung; loggt eine laute Warnung. Niemals in einem nicht vertrauenswürdigen Netz.