ObjectOSEnvironment Variables
ObjectOS runtime environment variable reference.
Environment Variables
Use environment variables for deployment-level configuration and secrets. Use system settings for tenant/user-editable application configuration.
Naming. All ObjectStack-owned variables use the
OS_prefix. Pre-1.0 unprefixed names (PORT,AUTH_SECRET,OS_MULTI_TENANT, …) still work but emit a one-shot deprecation warning. Prefer the canonicalOS_*names in new deployments; see Legacy aliases.
Core
| Variable | Required | Description |
|---|---|---|
OS_PORT | No | HTTP port the runtime listens on. Defaults to 3000. Legacy alias: PORT. |
OS_AUTH_SECRET | Yes for auth | Base secret used to derive per-project auth secrets. Legacy alias: AUTH_SECRET. |
Artifact and project resolution
| Variable | Required | Description |
|---|---|---|
OS_ARTIFACT_FILE | File mode | Path or http(s):// URL to a compiled objectstack.json. Read by the ObjectOS config and passed as artifactPath to createStandaloneStack. Point this at a published cloud artifact URL for cloud-connected deployments. |
OS_ARTIFACT_PATH | Alternative | Framework-level name for the same path or URL, honoured by @objectstack/runtime directly (CLI dev/start). Defaults to <cwd>/dist/objectstack.json. |
OS_PROJECT_ID | Optional | Legacy alias for OS_ENVIRONMENT_ID, accepted by the ObjectOS config for backward compatibility. Prefer OS_ENVIRONMENT_ID in new deployments. |
OS_ENVIRONMENT_ID | Optional | Environment id for the standalone stack (default proj_local). Also used to derive the per-project auth secret. The ObjectOS config also accepts the legacy alias OS_PROJECT_ID. |
OS_ORGANIZATION_ID | Optional | Default organization id for file-backed mode (default org_local). |
OS_MCP_SERVER_ENABLED | No | Set to true to expose the Model Context Protocol server over Streamable HTTP at /api/v1/mcp (8.0+). Off by default — the endpoint returns 404 until enabled, and requires an authenticated principal once on. |
OS_CLOUD_URL | Optional | Control-plane base URL for the marketplace proxy and local package install. Set to off or local to disable marketplace features. No longer used for host-stack hostname routing in the standalone distribution. |
OS_MULTI_ORG_ENABLED | No | Set to true to enable multi-tenant routing / organization switching (default false). Legacy alias: OS_MULTI_TENANT. |
OS_RUNTIME_PORT | Dev only | Localhost port used to build platform-SSO callback URLs when developing on http://localhost:<port>. |
Artifact hot-reload. The standalone stack reloads the local artifact automatically outside production (gated by
NODE_ENV); the explicitOS_WATCH_ARTIFACT=1flag from 7.x is no longer required.
Cache
| Variable | Default | Description |
|---|---|---|
OS_KERNEL_CACHE_SIZE | 32 | Maximum cached project kernels. |
OS_KERNEL_TTL_MS | 900000 | Idle TTL for project kernels. |
OS_ENV_CACHE_TTL_MS | 300000 | Environment/hostname cache TTL. |
OS_ARTIFACT_CACHE_TTL_MS | 300000 | Artifact response cache TTL. |
Auth and trusted origins
| Variable | Description |
|---|---|
AUTH_SECRET | Legacy alias for OS_AUTH_SECRET. Still honoured this release; prefer OS_AUTH_SECRET. |
OS_TRUSTED_ORIGINS | Comma-separated additional trusted origins. |
OS_ROOT_DOMAIN | Root domain used to trust project subdomains in platform SSO deployments. |
OS_PLATFORM_SSO | Set to false to disable platform SSO wiring. |
OS_RUNTIME_PORT | Local development helper for localhost project hostnames. |
Database
In cloud-connected mode the control plane returns the per-project runtime database configuration with the artifact response. In file-backed mode ObjectOS reads datasource declarations from the artifact. As a last resort the framework also honours:
| Variable | Description |
|---|---|
OS_DATABASE_URL | Connection URL (file:./db.sqlite, libsql://…, postgres://…, mongodb://…, memory://). Used by standalone mode and CLI dev. |
OS_DATABASE_DRIVER | Override the driver auto-detected from the URL. |
OS_DATABASE_AUTH_TOKEN | Auth token for managed drivers such as Turso/libSQL. |
OS_BUSINESS_DB_URL | ObjectOS wrapper convention for the per-project business database URL. Resolve it to OS_DATABASE_URL or a runtime datasource override in your deployment. |
OS_CACHE_DIR | Local artifact and runtime cache directory (default /var/cache/objectos). |
OS_SKIP_SCHEMA_SYNC | Set to 1 to skip ObjectQL DDL sync at boot. Use when schema is managed out-of-band. |
For ObjectOS customer deployments, prefer explicit control-plane runtime configuration or artifact datasource configuration over relying on container-local defaults.
Observability
Tracing and metrics export is opt-in. The exporter defaults to noop, so a
deployment emits nothing until you select one — setting an endpoint alone does
nothing.
| Variable | Default | Description |
|---|---|---|
OS_OBS_EXPORTER | noop | Telemetry exporter: noop | console | json | otlp. Use console/json for local debugging, otlp for a collector. |
OS_OTLP_ENDPOINT | — | OTLP/HTTP root URL (e.g. https://otlp.grafana.net/otlp). Required when OS_OBS_EXPORTER=otlp; if empty the runtime warns and falls back to noop. |
OS_OTLP_HEADERS | — | Extra OTLP headers (e.g. auth) as comma-separated key=value pairs. |
OS_OBS_SERVICE_NAME | — | service.name resource attribute on emitted spans/metrics. |
OS_OBS_DEPLOYMENT_ENV | production | deployment.environment resource attribute. |
OS_OTLP_FLUSH_MS | — | Flush interval for the OTLP exporter, in milliseconds. |
Settings namespace overrides
System settings (the tenant/user-editable ai, email, feature_flags, …
namespaces) can be pinned at the deployment level with an environment variable
named OS_<NAMESPACE>_<KEY> — uppercased, with . and - replaced by _.
For example ai.openai_base_url → OS_AI_OPENAI_BASE_URL, and
feature_flags.ai_enabled → OS_FEATURE_FLAGS_AI_ENABLED. As of 9.0 the
unprefixed aliases were removed — the OS_-prefixed form is the only one read.
Google sign-in (configurable in Setup → Authentication) also reads
GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET at the deployment level.
Legacy aliases
These pre-1.0 names still work this release but emit a one-shot deprecation warning. They will be removed in a future major. Prefer the canonical name.
| Canonical | Legacy |
|---|---|
OS_PORT | PORT |
OS_AUTH_SECRET | AUTH_SECRET |
OS_MULTI_ORG_ENABLED | OS_MULTI_TENANT |
OS_ENVIRONMENT_ID | OS_PROJECT_ID |