Umgebungsvariablen

Verwenden Sie Umgebungsvariablen für Konfiguration und Geheimnisse auf Deployment-Ebene. Verwenden Sie Systemeinstellungen für anwendungsbezogene Konfiguration, die von Mandanten/Benutzern bearbeitet werden kann.

Benennung. Alle ObjectStack-eigenen Variablen verwenden das Präfix OS_. Unpräfixierte Pre-1.0-Namen (PORT, AUTH_SECRET, OS_MULTI_TENANT, …) funktionieren weiterhin, geben aber eine einmalige Verwarnung zur Veralterung aus. Bevorzugen Sie die kanonischen OS_*-Namen in neuen Deployments; siehe Veraltete Aliasse.

Kern

Variable	Erforderlich	Beschreibung
`OS_PORT`	Nein	HTTP-Port, auf dem die Laufzeit lauscht. Standardwert ist `3000`. Veralteter Alias: `PORT`.
`OS_AUTH_SECRET`	Ja für Auth	Basisgeheimnis, aus dem projektspezifische Auth-Geheimnisse abgeleitet werden. Veralteter Alias: `AUTH_SECRET`.

Artefakt- und Projektauflösung

Variable	Erforderlich	Beschreibung
`OS_ARTIFACT_FILE`	Dateimodus	Pfad oder `http(s)://`-URL zu einer kompilierten `objectstack.json`. Wird von der ObjectOS-Konfiguration gelesen und als `artifactPath` an `createStandaloneStack` übergeben. Für cloud-verbundene Deployments auf eine veröffentlichte Artifact-URL zeigen lassen.
`OS_ARTIFACT_PATH`	Alternative	Framework-Name für denselben Pfad oder dieselbe URL, direkt von `@objectstack/runtime` berücksichtigt (CLI `dev`/`start`). Standard: `<cwd>/dist/objectstack.json`.
`OS_PROJECT_ID`	Optional	Veralteter Alias für `OS_ENVIRONMENT_ID`, der von der ObjectOS-Konfiguration aus Gründen der Abwärtskompatibilität akzeptiert wird. Bevorzugen Sie `OS_ENVIRONMENT_ID` in neuen Deployments.
`OS_ENVIRONMENT_ID`	Optional	Umgebungs-ID für den Standalone-Stack (Standard `proj_local`). Wird auch zur Ableitung des projektspezifischen Auth-Geheimnisses verwendet. Die ObjectOS-Konfiguration akzeptiert außerdem den veralteten Alias `OS_PROJECT_ID`.
`OS_ORGANIZATION_ID`	Optional	Standard-Organisations-ID für den dateibasierten Modus (Standard `org_local`).
`OS_MCP_SERVER_ENABLED`	Nein	Auf `true` setzen, um den Model-Context-Protocol-Server über Streamable HTTP unter `/api/v1/mcp` bereitzustellen (8.0+). Standardmäßig aus — der Endpunkt gibt `404` zurück, bis er aktiviert ist, und erfordert dann einen authentifizierten Principal.
`OS_CLOUD_URL`	Optional	Basis-URL der Steuerungsebene für den Marketplace-Proxy und die lokale Paketinstallation. Auf `off` oder `local` setzen, um Marketplace-Funktionen zu deaktivieren. Wird in der Standalone-Distribution nicht mehr für das Hostname-Routing des Host-Stacks verwendet.
`OS_MULTI_ORG_ENABLED`	Nein	Auf `true` setzen, um Multi-Mandanten-Routing / Organisationswechsel zu aktivieren (Standard `false`). Veralteter Alias: `OS_MULTI_TENANT`.
`OS_RUNTIME_PORT`	Nur Dev	Localhost-Port, der zum Aufbau von Plattform-SSO-Callback-URLs bei der Entwicklung auf `http://localhost:<port>` verwendet wird.

Artefakt-Hot-Reload. Der Standalone-Stack lädt das lokale Artefakt außerhalb der Produktion automatisch neu (gesteuert durch NODE_ENV); das explizite OS_WATCH_ARTIFACT=1-Flag aus 7.x ist nicht mehr erforderlich.

Cache

Variable	Standard	Beschreibung
`OS_KERNEL_CACHE_SIZE`	`32`	Maximale Anzahl zwischengespeicherter Projektkernel.
`OS_KERNEL_TTL_MS`	`900000`	Leerlauf-TTL für Projektkernel.
`OS_ENV_CACHE_TTL_MS`	`300000`	TTL des Umgebungs-/Hostnamen-Caches.
`OS_ARTIFACT_CACHE_TTL_MS`	`300000`	TTL des Artefakt-Antwort-Caches.

Auth und vertrauenswürdige Ursprünge

Variable	Beschreibung
`AUTH_SECRET`	Veralteter Alias für `OS_AUTH_SECRET`. Wird in diesem Release noch berücksichtigt; bevorzugen Sie `OS_AUTH_SECRET`.
`OS_TRUSTED_ORIGINS`	Kommagetrennte zusätzliche vertrauenswürdige Ursprünge.
`OS_ROOT_DOMAIN`	Root-Domain, die zum Vertrauen von Projekt-Subdomains in Plattform-SSO-Deployments verwendet wird.
`OS_PLATFORM_SSO`	Auf `false` setzen, um die Plattform-SSO-Verdrahtung zu deaktivieren.
`OS_RUNTIME_PORT`	Hilfe für die lokale Entwicklung von localhost-Projekt-Hostnamen.

Datenbank

Im cloud-verbundenen Modus gibt die Steuerungsebene die projektspezifische Laufzeit-Datenbankkonfiguration mit der Artefaktantwort zurück. Im dateibasierten Modus liest ObjectOS Datenquellendeklarationen aus dem Artefakt. Als letzten Ausweg berücksichtigt das Framework außerdem:

Variable	Beschreibung
`OS_DATABASE_URL`	Verbindungs-URL (`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). Wird vom Standalone-Modus und der CLI `dev` verwendet.
`OS_DATABASE_DRIVER`	Überschreibt den aus der URL automatisch erkannten Treiber.
`OS_DATABASE_AUTH_TOKEN`	Auth-Token für verwaltete Treiber wie Turso/libSQL.
`OS_BUSINESS_DB_URL`	ObjectOS-Wrapper-Konvention für die projektspezifische Geschäftsdatenbank-URL. Lösen Sie sie in Ihrem Deployment zu `OS_DATABASE_URL` oder einer Laufzeit-Datenquellen-Überschreibung auf.
`OS_CACHE_DIR`	Lokales Verzeichnis für Artefakt- und Laufzeit-Cache (Standard `/var/cache/objectos`).
`OS_SKIP_SCHEMA_SYNC`	Auf `1` setzen, um die ObjectQL-DDL-Synchronisierung beim Start zu überspringen. Verwenden, wenn das Schema außerhalb verwaltet wird.

Bevorzugen Sie für ObjectOS-Kundendeployments eine explizite Laufzeitkonfiguration der Steuerungsebene oder eine Artefakt-Datenquellenkonfiguration, anstatt sich auf container-lokale Standardwerte zu verlassen.

Observability

Der Export von Traces und Metriken ist opt-in. Der Exporter ist standardmäßig noop, sodass ein Deployment nichts ausgibt, bis Sie einen auswählen — allein einen Endpunkt zu setzen, bewirkt nichts.

Variable	Standard	Beschreibung
`OS_OBS_EXPORTER`	`noop`	Telemetrie-Exporter: `noop` \| `console` \| `json` \| `otlp`. Verwenden Sie `console`/`json` für lokales Debugging, `otlp` für einen Collector.
`OS_OTLP_ENDPOINT`	—	OTLP/HTTP-Root-URL (z. B. `https://otlp.grafana.net/otlp`). Erforderlich, wenn `OS_OBS_EXPORTER=otlp`; ist sie leer, warnt die Laufzeit und fällt auf `noop` zurück.
`OS_OTLP_HEADERS`	—	Zusätzliche OTLP-Header (z. B. Auth) als kommagetrennte `key=value`-Paare.
`OS_OBS_SERVICE_NAME`	—	Ressourcenattribut `service.name` auf ausgegebenen Spans/Metriken.
`OS_OBS_DEPLOYMENT_ENV`	`production`	Ressourcenattribut `deployment.environment`.
`OS_OTLP_FLUSH_MS`	—	Flush-Intervall für den OTLP-Exporter, in Millisekunden.

Überschreibungen von Einstellungs-Namespaces

Systemeinstellungen (die von Mandanten/Benutzern bearbeitbaren Namespaces ai, email, feature_flags, …) können auf Deployment-Ebene mit einer Umgebungsvariablen namens OS_<NAMESPACE>_<KEY> festgelegt werden — in Großbuchstaben, wobei . und - durch _ ersetzt werden. Zum Beispiel ai.openai_base_url → OS_AI_OPENAI_BASE_URL und feature_flags.ai_enabled → OS_FEATURE_FLAGS_AI_ENABLED. Ab 9.0 wurden die unpräfixierten Aliasse entfernt — die OS_-präfixierte Form ist die einzige, die gelesen wird.

Die Google-Anmeldung (konfigurierbar unter Setup → Authentication) liest außerdem GOOGLE_CLIENT_ID und GOOGLE_CLIENT_SECRET auf Deployment-Ebene.

Veraltete Aliasse

Diese Pre-1.0-Namen funktionieren in diesem Release noch, geben aber eine einmalige Verwarnung zur Veralterung aus. Sie werden in einer zukünftigen Hauptversion entfernt. Bevorzugen Sie den kanonischen Namen.

Kanonisch	Veraltet
`OS_PORT`	`PORT`
`OS_AUTH_SECRET`	`AUTH_SECRET`
`OS_MULTI_ORG_ENABLED`	`OS_MULTI_TENANT`
`OS_ENVIRONMENT_ID`	`OS_PROJECT_ID`

Umgebungsvariablen

On this page