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. As of the next release, 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 to a local compiled objectstack.json. Read by the ObjectOS app wrapper and forwarded as fileConfig.artifactPath. |
OS_ARTIFACT_PATH | Alternative | Framework-level name for the same path or http(s):// URL. Honoured by @objectstack/runtime directly (CLI dev/start, standalone mode). |
OS_PROJECT_ID | Optional | Legacy alias for OS_ENVIRONMENT_ID, accepted by the ObjectOS wrapper for backward compatibility. Prefer OS_ENVIRONMENT_ID in new deployments. |
OS_ENVIRONMENT_ID | Optional | Environment id for standalone/file-backed mode (default proj_local). Also used to derive the per-project auth secret. The ObjectOS wrapper also accepts the legacy alias OS_PROJECT_ID. |
OS_ORGANIZATION_ID | Optional | Default organization id for file-backed mode (default org_local). |
OS_WATCH_ARTIFACT | No | Set to 1 to reload the local artifact when it changes. Use only in development. |
OS_CLOUD_URL | Cloud mode | Control-plane base URL for hostname resolution and artifact fetch. Set to off or local to opt out of cloud-connected behaviour. |
OS_CLOUD_API_KEY | Optional | Bearer token for private control-plane Artifact API access. |
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>. |
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.
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 |