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.

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_TASK_TIMEOUT_MINUTES`	`90`	Hartes Timeout pro Agent-Task.
`MAX_PARALLEL_TASKS_PER_WORKSPACE`	`3`	Parallelitäts-Obergrenze pro Workspace.

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.

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 ein Runner beim Boot 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 wird beim ersten Eintausch verbraucht.
`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.