Environment variables — the full list
Canonical list of OS_* environment variables read by the ObjectStack runtime, CLI, and built-in plugins.
All ObjectStack-owned environment variables use the OS_ prefix. Variables are
read at startup unless noted otherwise. Boolean variables accept true / false
(case-insensitive); flag-style variables also accept 1 / 0 where noted.
Legacy names. Pre-1.0 unprefixed names (
PORT,DATABASE_URL,BETTER_AUTH_SECRET, …) still work this release and emit a one-shot deprecation warning. See Legacy aliases at the bottom of this page. Industry-standard third-party names (NODE_ENV,HOME,OPENAI_API_KEY,TURSO_*, OAuth*_CLIENT_ID/*_CLIENT_SECRET,RESEND_API_KEY,POSTMARK_TOKEN,AI_GATEWAY_*,SMTP_*) are not renamed and are read as-is by their respective libraries.
Runtime & Server
| Variable | Type | Default | Description |
|---|---|---|---|
OS_PORT | number | 3000 | HTTP listener port for os serve / os dev / os start. Resolution: --port › OS_PORT › PORT › 3000. |
OS_HOME | path | $HOME/.objectstack | ObjectStack config / state directory. |
OS_MODE | enum | standalone | Runtime mode. standalone | cloud. |
OS_BOOT_EMPTY | flag | 0 | When 1, boot the kernel with no metadata artifact (CLI internal). |
OS_MIGRATE_AND_EXIT | flag | 0 | When 1, run pending migrations and exit (suitable for one-shot jobs). |
OS_DISABLE_CONSOLE | flag | 0 | When 1, do not mount the Console portal under /_console. |
OS_CONSOLE_CSP_CONNECT_SRC | list | — | Extra connect-src sources for the Console document's content-security-policy, separated by spaces: a scheme (https:) or a scheme with a host (https://tiles.example.com). Name the host of any map view mapStyle that is not the default demo style, and the tile, sprite and glyph hosts of a style that keeps them elsewhere; the server itself, the default map style host, the OS_CONSOLE_MAP_STYLE_URL origin and a configured OS_TELEMETRY_CLIENT_ERROR_REPORTING_DSN origin are already allowed. A malformed entry refuses the boot. |
OS_CONSOLE_MAP_STYLE_URL | URL | — | The deployment's default map style document (for example https://tiles.example.com/styles/basic/style.json). Served as mapStyleUrl on GET /api/v1/runtime/config, which is anonymous, so the URL is public; its origin joins the Console's connect-src. Unset, no mapStyleUrl is served. Must be an absolute https: URL on a host name, with no user name or password; anything else refuses the boot. |
OS_EAGER_SCHEMAS | flag | 0 | When 1, evaluate all lazily-built Zod spec schemas eagerly at module load instead of on first use — an emergency rollback of the lazy-schema memory optimization (higher startup RSS). |
OS_SKIP_SCHEMA_SYNC | flag | 0 | When 1, skip the implicit db:sync on boot. Use after running migrations manually. |
Port conflicts behave differently by mode. In dev (
os dev, orNODE_ENV=development) a busy port auto-hops to the next free one (up to +100) and the banner prints the actual bound port. In production (os start) a busy port is a hard error (exit 1) — it never silently drifts, because a shifted port breaks reverse-proxy upstreams,OS_AUTH_URLcallbacks, andOS_TRUSTED_ORIGINS(auth CSRF). Pin the port explicitly in production (OS_PORT=8080 os start) and keepOS_AUTH_URL/OS_TRUSTED_ORIGINSin sync with it.
Database & Storage
| Variable | Type | Default | Description |
|---|---|---|---|
OS_DATABASE_URL | url | — | Database connection string (e.g. file:./data.sqlite, :memory: for SQLite's own in-memory database, postgres://…, mysql://…, mongodb://…). memory:// and mingo:// name the in-memory (mingo) engine, which is not a boot store, and are refused at boot with a message naming the replacement. libsql:// / *.turso.io (Turso) is inferred too, but its driver is an optional package: npm install @objectstack/driver-turso, otherwise the boot fails loudly with that command — it never falls back to SQLite. |
OS_DATABASE_AUTH_TOKEN | string | — | Auth token for a libSQL/Turso connection (--database-auth-token). The vendor's own TURSO_AUTH_TOKEN is read as a fallback and is not renamed (see the third-party names note above). Ignored by every other driver — their credentials live in the URL. |
OS_DATABASE_DRIVER | enum | inferred | Force a specific driver when the URL is ambiguous. sqlite | sqlite-wasm | postgres | mysql | mongodb | turso. memory / mingo / in-memory are refused at boot: the in-memory engine cannot serve a tenant-scoped read, so use os dev --fresh or OS_DATABASE_URL=:memory: instead. mysql is a supported deployment target that carries three dialect caveats — two of them integrity guarantees MySQL cannot enforce at the database. Read MySQL dialect caveats before choosing it. |
OS_DATABASE_SQLITE_JOURNAL_MODE | enum | wal | Journal mode for file-backed SQLite. wal (default) lets a dev server and CLI commands share one file without blocking each other, and is what makes the os migrate occupancy check reliable. Set to delete for SQLite's rollback journal — required when the database lives on a network filesystem (NFS/SMB), where WAL cannot work. The setting is applied, not merely skipped: delete converts a database that already adopted WAL back. Ignored for :memory:, for the WASM SQLite driver, and for non-SQLite drivers. A per-datasource sqliteJournalMode in driver config outranks it. See Journal mode. |
OS_DATABASE_POOL_MAX | integer | 5 | Maximum pooled connections each replica opens to postgres / mysql. The pool, not the database, is usually what caps authed throughput on a multi-replica deployment: at the default of 5 a 3-replica cluster reaches at most ~15 connections, which can plateau the data API while the database still has most of its max_connections free. Size it so replicas × OS_DATABASE_POOL_MAX stays below the database's max_connections, leaving headroom for migrations and admin connections — e.g. 3 replicas × 40 = 120 against max_connections=200. A per-datasource pool.max in the datasource's own definition outranks it, and with the variable unset nothing changes. A value that is not a positive integer refuses the boot rather than falling back to the default. Ignored by memory / sqlite / sqlite-wasm / turso, which open no pool — declaring a pool block on those is an error, not a silent drop. |
OS_ALLOW_DRIVER_CONNECT_FAILURE | boolean | false | Escape hatch for the driver-connect boot guard. By default a data driver that fails to connect at startup refuses the boot — a server that cannot reach its database must not report itself started and then fail every request. The same guard covers a declared datasource that objects bind to via datasource: '…', or an external one with validation.onMismatch: 'fail': those objects have no fallback datasource, so an unconnected one means they are all dead. Set to 1 to boot anyway, in an explicitly degraded state logged loudly at startup. There is no reconnection: whatever failed stays dead for the process lifetime and every query and schema sync routed to it fails. |
OS_STORAGE_LOCAL_ROOT | path | ./.objectstack/data/uploads | Root directory for the local file storage adapter, relative to the process cwd (used by os serve's default storage capability wiring). This is the same value as Setup → Settings → File Storage → Root directory; setting it here pins that field (it shows as locked-by-env). Renamed from OS_STORAGE_ROOT — see below. |
OS_STORAGE_ROOT | path | — | Deprecated alias for OS_STORAGE_LOCAL_ROOT. Still read for one release, with a startup warning; it will be removed in a future major. Rename it now. Before the rename the two halves of the platform spelled this value differently — the CLI wrote OS_STORAGE_ROOT while the settings service read OS_STORAGE_LOCAL_ROOT — so any value other than the default was silently discarded at startup and uploads landed in ./.objectstack/data/uploads regardless. If you set OS_STORAGE_ROOT on an older release, check where your uploads actually are before assuming a backup covered them. |
OS_STORAGE_LOCAL_ROOT_SHARED | boolean | — | Declares that the local storage root is one volume every replica mounts (for example a named volume several Compose replicas on one host share). Read only when several replicas are declared (OS_EXPECT_MULTI_NODE=true or OS_CLUSTER_REPLICAS greater than 1) over the redis cluster driver: there the local storage adapter refuses the boot — and a storage settings change onto it is not applied — unless this is true, because each replica would otherwise write uploads to its own disk and a file uploaded through one would be missing on the others. Use S3 instead where the volume cannot be shared (a ReadWriteOnce volume cannot): OS_STORAGE_ADAPTER=s3 with OS_STORAGE_S3_BUCKET / OS_STORAGE_S3_REGION, or Setup → Settings → File Storage. It is a declaration, not a check: nothing verifies the volume is really shared. A single node, any other cluster driver and the S3 adapter ignore it. Deployment config only, never a settings row. |
OS_ARTIFACT_PATH | path | — | Path or http(s):// URL to a compiled objectstack.json artifact to boot the kernel from. |
OS_ARTIFACT_URL | url | — | Boot a published artifact by reference — https://…/hotcrm-2.2.2.json (fetched at boot) or file:///…/objectstack.json (read directly, the volume-mount workflow). Overrides OS_ARTIFACT_PATH and any objectstack.config.ts in the working directory; --artifact still wins. Optionally pinned with an SRI-style fragment: …/hotcrm-2.2.2.json#sha256=<64 hex chars> — there is deliberately no companion OS_ARTIFACT_SHA256, because a URL fragment is client-side by standard (never sent to the server) and so travels with the reference as one value. See Artifact-pinned boot. |
Printing
Read by @objectstack/service-print when PrintServicePlugin is composed; see Print Pages. Configure one placement plus the console URL; a plugin option of the same purpose wins over its variable.
| Variable | Type | Default | Description |
|---|---|---|---|
OS_PRINT_CHROMIUM_PATH | path | — | Local placement: a Chromium executable on this host, launched per print (plugin option chromiumPath). |
OS_PRINT_BROWSER_ENDPOINT | url | — | Remote placement: a browser's DevTools WebSocket endpoint, connected per print (option browserEndpoint). The minted session cookie travels in its frames, so use wss:// off this host and ws:// only on loopback. Never logged beyond its scheme and host. Setting it together with OS_PRINT_CHROMIUM_PATH is refused. |
OS_PRINT_CONSOLE_URL | url | — | The console URL that browser loads, /_console included (option consoleUrl). A URL carrying credentials (user:password@) is refused: the browser signs in with the requesting user's own session. |
Secrets & Clustering
| Variable | Type | Default | Description |
|---|---|---|---|
OS_SECRET_KEY | string | — | 32-byte master key (64 hex chars or base64) for sys_secret encryption — encrypted settings, secret fields, datasource credentials. Required for containerized or multi-node deployments; on a single durable host os start mints and persists a dev key instead. See Self-Hosted Deployment. |
OS_DEV_CRYPTO_KEY | string | — | Development convenience crypto key, consulted after OS_SECRET_KEY. Do not use in production. |
OS_CLUSTER_DRIVER | string | memory | Cluster coordination driver id. When set to anything other than memory, the runtime treats the deployment as multi-node (and requires OS_SECRET_KEY). Non-memory drivers are opt-in sibling packages (e.g. redis via @objectstack/service-cluster-redis) — see Cluster. |
OS_REDIS_URL | url | — | Connection URL passed to a non-memory cluster driver (e.g. OS_CLUSTER_DRIVER=redis). |
OS_AUTHZ_GRANTS_CACHE_TTL_MS | number | 0 | Staleness bound, in milliseconds, for the cross-request authorization grants cache (#11633). 0 (the default) means off — a real path, not a degenerate TTL. A non-zero value caches the resolved authorization grants envelope (resolveUserAuthzGrants — positions, permission sets, posture, RLS peer ids) per (user, organization, seed) on each node. On the writing node the cache is retired immediately by any write to a watched authorization object (sys_member, sys_user_position, sys_user_permission_set, sys_user, sys_metadata_activation) and by any metadata.changed (positions and permission sets are catalog definitions, so a change to one is a metadata change); sys_session is deliberately not watched, so session-activity writes cannot flush it. Entries additionally expire at the earliest upcoming ADR-0091 validity boundary — min(ttl, nextBoundary) — because a valid_until passing is a permission change with no write anywhere. The permission explainer and runAs:'user' automation runs always read uncached. When a value is set with no cross-node invalidation bus — no cluster service, or the in-process memory driver, which fans out to nobody — the boot says so loudly, every time: the TTL is then the whole bound on how long this replica may honour a grant another replica revoked. A malformed value is treated as 0 and warned about rather than silently read as "disabled". Deployment config only; it is deliberately not a settings row, because a cached path must not serve the knob that bounds the cache. |
Authentication
| Variable | Type | Default | Description |
|---|---|---|---|
OS_AUTH_URL | url | http://localhost:<OS_PORT>, or https://localhost:<OS_PORT> when os dev terminates TLS (--cert / --key) | Public base URL of the auth server. Required behind a proxy or in production. When set it always wins, whatever the listener speaks — it names where the deployment is reached, not what the process bound. |
OS_AUTH_SECRET | string | auto-generated (dev) | Secret used to sign sessions and cookies. Required in production. |
OS_AUTH_TWO_FACTOR | boolean | false | Enable the low-level better-auth two-factor plugin. Keep disabled unless your UI handles enrollment, login challenge, and backup-code recovery. |
OS_DISABLE_SIGNUP | boolean | false | When true, block new email/password sign-ups. Under the single posture the very first user can still sign up to bootstrap admin; under the walled postures no sign-up is ever promoted, so this leaves the deployment dependent on OS_PLATFORM_OWNER_EMAIL alone. |
OS_AUTH_EMAIL_PASSWORD_ENABLED | boolean | settings default | Settings env override for auth.email_password_enabled. Controls local email/password login. |
OS_AUTH_SIGNUP_ENABLED | boolean | settings default | Settings env override for auth.signup_enabled. Takes precedence over UI settings and is preferred over OS_DISABLE_SIGNUP. |
OS_AUTH_REQUIRE_EMAIL_VERIFICATION | boolean | settings default | Settings env override for auth.require_email_verification. Under the open audience posture, false is the deployment's opt-out from the forced verification (one boot warning; see Email verification under each posture); under email_domain it is refused, since verification is forced there. |
OS_AUTH_MEMBERSHIP_POLICY | auto | invite-only | auto | Settings env override for auth.membership_policy — what a newly created user joins (ADR-0093 D1). auto binds every new user to the deployment's default organization, except a sign-up admitted by its invitation alone whose address is unverified, which joins by accepting: under the invite_only audience posture, one admitted by the invitation it presents; under email_domain, one whose address is off the allowlist and which an invitation addressed to it admitted. invite-only grants membership solely through an explicit act: creating a workspace, accepting an invitation, an admin adding them, or SSO just-in-time provisioning. Applies to sign-up and to the backfill of pre-existing member-less users. An unrecognized value is rejected with an error log and ignored — the deployment keeps its current policy rather than silently reverting to auto. |
OS_ORG_INVITATION_LIMIT | integer | off | unset (100) | How many pending invitations one organization may hold at once. When the organization already holds that many, POST /api/v1/auth/organization/invite-member answers 403 INVITATION_LIMIT_REACHED (Invitation limit reached) until an invitation is accepted, rejected, cancelled or expires. Unset keeps the auth library's own limit of 100, so a deployment that sets nothing behaves as before. A positive integer N allows N. off, unlimited or none (any case) removes the limit, for a host that invites people in bulk. 0, or any value that is not plain digits (-5, 2.5, 1e3, 1_000), reads as unset (100), so a typo never refuses every invitation. The count is per organization, not per inviter. Read when the auth plugin builds its organization plugin, so a change needs a process reload. |
OS_AUTH_GOOGLE_ENABLED | boolean | settings default | Settings env override for auth.google_enabled. Requires Google OAuth credentials from Settings or env. |
GOOGLE_CLIENT_ID | string | — | Deployment-level Google OAuth client id for the open-source Google login implementation. |
GOOGLE_CLIENT_SECRET | string | — | Deployment-level Google OAuth client secret for the open-source Google login implementation. |
OS_AUTH_DIRECT_SIGN_IN_ENABLED | boolean | false | Send a signed-out visitor to the Console sign-in page straight to the identity provider, and back to the page they asked for. Wins over the auth plugin's directSignIn option. The sign-in page is still shown when no single provider can be started, after an identity-provider error, and for an OAuth client's hand-off. See Skip the sign-in page. |
OS_AUTH_DIRECT_SIGN_IN_PROVIDER | string | the one configured provider | The providerId direct sign-in uses: an oidcProviders entry or a registered SSO provider. Unset, the only configured provider is used; with none or several, the sign-in page is shown. |
OS_AUTH_DIRECT_SIGN_IN_LOCAL_PATH | hidden | off | hidden | With direct sign-in on, whether the Console sign-in form keeps the password form at /login?local=1 (hidden) or offers no local way in (off). Server-side password sign-in is unchanged either way. Any other value refuses to boot. |
OS_TENANCY_POSTURE | single | group | isolated | derived from OS_MULTI_ORG_ENABLED | Which organization wall the authorization kernel enforces (ADR-0105 D1). single = no wall. group = organization_id IN accessible_org_ids — organizations are membership boundaries over one shared dataset, with union read access across every organization the caller belongs to. isolated = organization_id = <active organization>, the hard legal-entity wall (formerly spelled multi). Unset derives from OS_MULTI_ORG_ENABLED (true ⇒ isolated, else single), so existing deployments are unchanged. An unrecognized value refuses to boot rather than silently falling back to a posture with no wall. Both walled postures require the enterprise @objectstack/organizations runtime — without it the request resolves to single and boot is refused unless OS_ALLOW_DEGRADED_TENANCY=1. |
OS_MULTI_ORG_ENABLED | boolean | false | Superseded by OS_TENANCY_POSTURE, and still honoured: true selects the isolated posture. When true, organization creation/switching UI is exposed. |
OS_AUTOMATION_SCHEDULED_WORK_ENABLED | boolean | false | Whether this deployment runs package-authored scheduled work: time-triggered flows (a type: 'schedule' flow with a config.schedule cadence, and the timeRelative sweep) and packaged defineJob cron jobs. OFF by default in every posture and every kernel — a clock-driven workload's cost is a fact about the deployment, not about the flow, so an author cannot decide it and no metadata key asks them to. Accepts true/1/on/yes (case-insensitive); anything else, including unset, is off. While it is off nothing arms, and every such flow is listed by getTriggerBindingAudit() and the CLI startup summary as disabled by deployment policy — never as a binding failure, and nothing about the flow needs fixing. While it is on, what a time-triggered flow owes depends on the posture: under isolated it must declare config.organization on its start node or it is not armed; under group the declaration is optional and an undeclared sweep reads group-wide with each run acting as its own swept record's organization (a record-less cron there carries none, and its tenant-scoped writes are refused — declare one if it writes); under single it needs no declaration and its runs carry no organization. ⛔ Platform-internal scheduled work — approvals escalation, the lifecycle Reaper, the messaging dispatch loop, membership backfill — is not gated by this: the boundary is authored by a package, not runs on the job service. os doctor prints the effective value. |
OS_PLATFORM_OWNER_EMAIL | csv | — | The deployment's platform administrators: one email address, or a comma-separated list. A caller resolves PLATFORM_ADMIN when their own stored sys_user row carries a declared address and reads email-verified. Comparison is trimmed and case-insensitive; duplicates collapse and blank entries are dropped. One unparseable entry refuses the whole variable rather than just that entry — the deployment then has zero configured administrators, loudly — because a silently narrower administrator set is the worse failure. Required under the walled postures (group / isolated): unset or blank there refuses to boot, since the first self-registrant is not promoted and no grant row is written. Unset under single is normal — that posture still promotes the first human account. Read live per resolution, so revocation is a config change plus a process reload; there is no runtime endpoint that changes it. See First boot: create the admin. |
OS_PLATFORM_OWNER_ORGANIZATION | string | — | Walled postures only (group / isolated): the id or slug of the platform operators' own organization. The boot upgrade reports raise deployment-level findings, such as the access upgrade report, as one error line addressed to the operator. With this set they are also raised in-app: one notification stamped with that organization and addressed to the OS_PLATFORM_OWNER_EMAIL operators, deduplicated per finding set across boots. No other organization is told. Use a dedicated organization that holds the operators only: every administrator of it can read the notification in Setup, Notification Events, and the findings can name other organizations' ids and rule names. Boot logs a warn for a configured operator who is not a verified member of it, and for an administrator of it who is not a configured operator. A value that names no organization logs one error naming the value and raises nothing in-app; it never falls back to another organization. Unset, the log line is the only channel. Ignored under single, where the Default Organization's administrators are told. |
OS_OIDC_PROVIDER_ENABLED | boolean | tracks MCP | When true, expose this instance as an OIDC identity provider. When unset it follows the MCP server surface (OS_MCP_SERVER_ENABLED, on by default) — the MCP human-client track is OAuth 2.1, so every MCP-enabled deployment is its own authorization server. |
OS_COOKIE_DOMAIN | string | — | Cookie domain for cross-subdomain session sharing (e.g. .example.com). |
OS_TRUSTED_ORIGINS | csv | — | Comma-separated list of origins permitted for auth callbacks / CSRF. |
OS_TRUSTED_APP_SCHEMES | csv | — | Comma-separated custom URL schemes of the native apps the mobile sign-in hand-off (GET /api/v1/auth/one-time-token/handoff) may redirect a one-time token to, e.g. ai.objectos.mobile. Read by os serve, and so by the serve that os dev and os start run; entries are trimmed and empty ones dropped. Each entry must be a lowercase reverse-domain scheme with no : suffix: a bad one fails the boot, naming it. Unset, no app is registered, the one-time-token plugin is not mounted, and the hand-off answers 400 for every target. |
OS_TERMS_URL | url | — | URL shown next to the "Terms of Service" link on the sign-up form. Empty string hides the link. |
OS_PRIVACY_URL | url | — | URL shown next to the "Privacy Policy" link on the sign-up form. Empty string hides the link. |
OS_TURNSTILE_SITE_KEY / OS_TURNSTILE_SECRET_KEY | string | — | Opt-in Cloudflare Turnstile on email sign-up. Set both and /sign-up/email (the register page and the first-run setup) requires a verified Turnstile token, the Console renders the challenge, and its content-security-policy admits https://challenges.cloudflare.com; sign-in and password reset are not challenged. Only the site key is served to the browser (features.turnstileSiteKey); the secret never leaves the server. With either unset nothing changes (one boot warn names the missing one). |
Auth settings precedence:
- Environment variables win over values saved in the Setup UI.
OS_AUTH_<SETTING_KEY>settings env vars are the canonical form for settings-backed auth controls.- Existing deployment toggles such as
OS_AUTH_TWO_FACTORandOS_DISABLE_SIGNUPremain supported. - Google credentials can be saved in Setup → Authentication.
google_client_secretis encrypted at rest. GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETremain supported for deployment-level Google OAuth configuration.
CORS
| Variable | Type | Default | Description |
|---|---|---|---|
OS_CORS_ENABLED | boolean | true | Enable CORS middleware. |
OS_CORS_ORIGIN | csv | — | Origins admitted to cross-origin requests: exact origins or patterns such as https://*.example.com, comma-separated. Unset, no cross-origin caller is admitted (loopback origins excepted on a development boot); same-origin requests, the Console included, need no entry. * is refused at boot unless OS_CORS_CREDENTIALS=false. |
OS_CORS_CREDENTIALS | boolean | true | Allow credentialed cross-origin requests from the admitted origins. Must be false to serve OS_CORS_ORIGIN=*. |
OS_CORS_MAX_AGE | number | 86400 | Preflight cache TTL in seconds. |
Outbound requests
Webhook deliveries and the flow http node (inline and durable: true) reach only
public addresses. Loopback, private (RFC 1918), carrier-grade NAT, link-local,
unique-local, multicast, broadcast, unspecified, documentation and benchmarking
addresses, every other special-purpose range that is not globally reachable, and any
IPv6 address outside global unicast (2000::/3) are refused — judged after DNS
resolution, on the connected socket and on every redirect — unless the target is
listed below. Link-local and cloud metadata addresses are never reachable, in any
IPv6 form that carries them. A refused
webhook delivery dead-letters at once as EGRESS_REFUSED; a refused http call
fails its node with EGRESS_REFUSED. The boot logs one line saying the guard is
active and how many targets are allowlisted, and the webhook plugin logs once how
many stored sys_webhook rows target an address the guard refuses. The guard needs a
Node.js runtime: at boot it proves that the requests it sends are judged by it, and
where it cannot, the boot fails and these requests are refused.
| Variable | Type | Default | Description |
|---|---|---|---|
OS_EGRESS_ALLOWED_TARGETS | csv | — | Internal targets these requests may reach: exact host names (hooks.internal), IP addresses (10.0.0.5, ::1) or CIDR blocks with host bits zero and a prefix of at least /8 (10.0.0.0/8, fd00::/8), comma-separated. No scheme, port, path or wildcard. A malformed or over-broad entry (such as 0.0.0.0/0) fails the boot. Link-local addresses (169.254.0.0/16, fe80::/10) and cloud metadata addresses can never be listed, and are refused even when a listed host name or block covers them. |
Branding
The console's product name, logo, favicon and colours are served by RuntimeConfigPlugin (@objectstack/cloud-connection) as the branding block of GET /api/v1/runtime/config, which the console reads on every page load. A host that constructs its own RuntimeConfigPlugin with an option of the same name (productName, logoUrl, …) outranks the variable. The first eight variables below are read once, when that plugin is constructed at boot: changing one takes a restart. A value saved in Setup → Branding is read per request instead (see the precedence below). Mail and auth are named separately, by OS_APP_NAME.
| Variable | Type | Default | Description |
|---|---|---|---|
OS_PRODUCT_NAME | string | ObjectOS | The console's product name (branding.productName): the browser-tab title (alone, or after the open app's label), the header's product mark, the sign-in pages, the loading screen and the installed-app (PWA) manifest's name. It does not name emails, the authenticator app entry or the MCP sign-in — OS_APP_NAME does — so an unconfigured deployment reads ObjectOS in the console and ObjectStack in its mail. Empty reads as unset. |
OS_PRODUCT_SHORT_NAME | string | the product name served | The PWA manifest's short_name (branding.productShortName). Unset, it is the product name actually served, which under single may be a saved Branding name. |
OS_PRODUCT_STAGE | enum | — (no stage key) | preview | beta | ga, matched exactly. Drives the console's top-bar chip (branding.stage): "Preview" for preview, "Beta" for beta, none for ga. Unset sends no stage key and the console keeps its own preview default, so the chip shows. Any other value (GA, general-availability) is refused with one warn at boot and treated as unset. |
OS_LOGO_URL | url | — | The product logo, absolute or relative (branding.logoUrl): the sign-in pages, the loading screen and the header's product mark. Unset, the console draws its built-in mark. |
OS_FAVICON_URL | url | — | The favicon, absolute or relative (branding.faviconUrl): the browser-tab icon and the PWA manifest's icon. While an app with its own branding.favicon is open, that icon replaces it. No Branding setting overrides this variable, on any posture. |
OS_BRAND_COLOR | string | — | The brand colour as hex, e.g. #4F46E5 (branding.brandColor). The console uses it as the installed-app theme colour, through OS_PWA_THEME_COLOR's default; each app's own AppBranding colours are separate. |
OS_PWA_DESCRIPTION | string | <product name> — runtime console | The PWA manifest's description (branding.pwaDescription). Unset, it is built from the product name actually served. |
OS_PWA_THEME_COLOR | string | the brand colour served, else #4f46e5 | The PWA manifest's theme_color (branding.pwaThemeColor), as hex. Unset, it is the brand colour actually served, else #4f46e5. |
OS_APP_NAME | string | — | The deployment's product name under objectstack serve for mail and auth: {{appName}} in every email template (auth emails included), the issuer an authenticator app lists a TOTP enrollment under, and the MCP OAuth resource name. Wins over config.email.appName, config.email.defaultTemplateContext.appName and config.appName; with none of them set the name is ObjectStack. Under single, an explicitly set branding.workspace_name setting outranks it in auth (the authenticator issuer takes a change only when the auth instance is rebuilt, such as at a restart); under group / isolated nothing does. It never names the console — that is OS_PRODUCT_NAME. |
Branding precedence, by tenancy posture (OS_TENANCY_POSTURE):
single— three fields read thebrandingsettings namespace on every request, so a save in Setup → Branding shows on the next page load with no restart:workspace_name→productName,logo_url→logoUrl,accent_color→brandColor. Each takes the first source that is set: the setting (a value saved in Setup, or the settings layer's ownOS_BRANDING_WORKSPACE_NAME/OS_BRANDING_LOGO_URL/OS_BRANDING_ACCENT_COLOR, which outranks a saved value and locks the field), then the host'sRuntimeConfigPluginoption, thenOS_PRODUCT_NAME/OS_LOGO_URL/OS_BRAND_COLOR, then the built-in default. The Branding page'sworkspace_name(labelled Product name) declares no default of its own: left empty, the name comes from the sources after it. A setworkspace_namealso names sign-in emails, the authenticator app entry and the MCP sign-in, ahead ofOS_APP_NAME.group/isolated— thebrandingnamespace is not offered: it is absent fromGET /api/settings,GETandPUT /api/settings/brandinganswer404 UNKNOWN_NAMESPACE, and Setup lists no Branding entry. TheOS_BRANDING_*variables are not read. The console's branding is the host option, then the variables in this table, then the default, and the auth product name is theOS_APP_NAMEchain alone. A walled deployment that setOS_BRANDING_WORKSPACE_NAMEmoves the value toOS_APP_NAME.
On every posture productShortName, pwaDescription and pwaThemeColor follow the name and colour actually served unless set themselves, and OS_PRODUCT_STAGE and OS_FAVICON_URL have no setting above them.
Link previews read the same values. The console document served at /_console/ carries them in tags written on the server, since a preview crawler runs no script: <title> and og:title (productName), <meta name="description"> and og:description (pwaDescription), and og:image (logoUrl, resolved against the request origin). og:url is the request origin. A value that is not served writes no tag.
| Variable | Type | Default | Description |
|---|---|---|---|
OS_EMAIL_PROVIDER | enum | log | Transport. log | smtp | resend | postmark. log (default) prints to stdout without sending — it is also how a deployment declares that it does not send mail. Any other value is a delivery intent, and a boot that cannot honour it fails loudly instead of substituting the log transport. |
OS_EMAIL_API_KEY | string | — | API key for resend / postmark. Required when either is selected — a boot without it fails rather than starting with a transport that records every message in sys_email as sent and delivers nothing. Set OS_EMAIL_PROVIDER=log for environments that should not send mail. |
OS_EMAIL_FROM | — | Default From: address. | |
OS_EMAIL_RETRIES | number | 0 | Retry count for transient send failures (0 = no retry). |
OS_EMAIL_SMTP_HOST | string | — | SMTP server hostname. Required when OS_EMAIL_PROVIDER=smtp — a boot without it fails loudly rather than starting with a transport that logs mail instead of sending it. |
OS_EMAIL_SMTP_PORT | number | 587 | SMTP port. 465 selects implicit TLS (SMTPS). |
OS_EMAIL_SMTP_SECURE | boolean | true | Require TLS. On port 465 that means implicit TLS; on any other port a required STARTTLS upgrade (a server that will not upgrade fails the send instead of leaking credentials in the clear). false connects in the clear and upgrades only when STARTTLS is offered. |
OS_EMAIL_SMTP_USER | string | — | SMTP AUTH username. Omit for servers that accept unauthenticated relay. |
OS_EMAIL_SMTP_PASSWORD | string | — | SMTP AUTH password. |
OS_EMAIL_APP_SEND_HOURLY_LIMIT | number | 200 | The most messages an organization's mail log may record in one hour before a script body's ctx.email.send is refused with 429 RATE_LIMIT_EXCEEDED. A whole number, 0 or more; any other value fails the call. The count is read before each send, so it bounds volume rather than holding an exact number. See Email service. |
SMTP delivery ships in
@objectstack/plugin-email(ADR-0012) and is implemented withnodemailer, imported lazily so deployments that never select SMTP — and non-Node runtimes — never loadnode:net/node:tls. Any provider that speaks SMTP works through it: a corporate mail server, Aliyun DirectMail, Tencent SES, QQ / 163 enterprise mailboxes.These variables configure the transport at boot. The same connection can be configured at runtime in Settings → Mail (namespace
smtp_host/smtp_port/smtp_secure/smtp_user/smtp_password), which hot-swaps the live transport without a restart and whose Send test email button performs a real delivery. Settings-page values are overridden by the namespace's ownOS_MAIL_*env door (e.g.OS_MAIL_SMTP_HOST), which locks the field in the UI.
AI
These variables configure the ObjectOS in-product AI runtime, which is not
part of the open-source framework. The open-source framework has no
in-UI AI runtime to configure: it exposes AI through @objectstack/mcp (BYO-AI),
where the model and provider are configured in your own MCP client (Claude,
Cursor, a local model, …). See the AI Capabilities guide.
| Variable | Type | Default | Description |
|---|---|---|---|
AI_GATEWAY_MODEL | string | — | Vercel AI Gateway model id (for example openai/gpt-4.1-mini or anthropic/claude-sonnet-4-5). When set, the AI service boots with the gateway adapter before trying direct providers. |
AI_GATEWAY_API_KEY | string | — | Vercel AI Gateway API key. Required by the gateway SDK for real gateway calls; by itself it does not select the gateway adapter. Pair it with AI_GATEWAY_MODEL. |
OPENAI_API_KEY | string | — | Selects the direct OpenAI adapter when no gateway model is configured. Default model: gpt-4o. |
ANTHROPIC_API_KEY | string | — | Selects the direct Anthropic adapter when gateway and OpenAI are not configured. Default model: claude-sonnet-4-20250514. |
GOOGLE_GENERATIVE_AI_API_KEY | string | — | Selects the direct Google Gemini adapter when gateway, OpenAI, and Anthropic are not configured. Default model: gemini-2.0-flash. |
OS_AI_MODEL | string | provider default | Overrides the model id for direct OpenAI / Anthropic / Google provider detection. Does not override AI_GATEWAY_MODEL; gateway model ids already include the provider prefix. |
OS_AI_ACTION_API_BASE_URL | url | — | Base URL prepended to relative type: 'api' action targets exposed as AI tools. Without this or a plugin apiActionBaseUrl, relative API actions are skipped for AI exposure. |
OS_AI_PROVIDER | enum | — | Settings override for the AI provider. Supported values include gateway, openai, anthropic, google, deepseek, dashscope, cloudflare, siliconflow, and openrouter. When set, it locks the Settings UI value. |
OS_AI_GATEWAY_MODEL | string | — | Settings override for the Vercel AI Gateway model id. Use with OS_AI_PROVIDER=gateway. |
OS_AI_GATEWAY_API_KEY | string | — | Settings override for the Vercel AI Gateway API key. Use with OS_AI_PROVIDER=gateway. |
OS_AI_OPENAI_BASE_URL | url | — | Settings override for the OpenAI-compatible chat base URL. Use with OS_AI_PROVIDER=openai for Azure, local gateways, or third-party OpenAI-shaped APIs. |
OS_AI_OPENAI_API_KEY | string | — | Settings override for the OpenAI-compatible API key. Stored only in env; the Settings UI cannot overwrite it while present. |
OS_AI_OPENAI_MODEL | string | gpt-4o | Settings override for the OpenAI-compatible chat model id. |
OS_AI_ANTHROPIC_API_KEY | string | — | Settings override for the Anthropic API key. Use with OS_AI_PROVIDER=anthropic. |
OS_AI_ANTHROPIC_MODEL | string | claude-sonnet-4-20250514 | Settings override for the Anthropic model id. |
OS_AI_GOOGLE_API_KEY | string | — | Settings override for the Google Generative AI API key. Use with OS_AI_PROVIDER=google. |
OS_AI_GOOGLE_MODEL | string | gemini-2.0-flash | Settings override for the Google model id. |
OS_AI_<PROVIDER>_API_KEY | string | — | Settings override for preset OpenAI-compatible providers, for example OS_AI_DEEPSEEK_API_KEY, OS_AI_DASHSCOPE_API_KEY, OS_AI_SILICONFLOW_API_KEY, or OS_AI_OPENROUTER_API_KEY. |
OS_AI_<PROVIDER>_MODEL | string | provider default | Settings override for preset provider model ids, for example OS_AI_DEEPSEEK_MODEL=deepseek-chat. |
The boot-time LLM adapter priority is:
- Explicit
AIServicePlugin({ adapter })or per-plugingatewayModeloption. AI_GATEWAY_MODELusing@ai-sdk/gateway.OPENAI_API_KEYusing@ai-sdk/openai.ANTHROPIC_API_KEYusing@ai-sdk/anthropic.GOOGLE_GENERATIVE_AI_API_KEYusing@ai-sdk/google.MemoryLLMAdapterecho mode when no real provider is configured.
After boot, if the Settings service is mounted, the ObjectOS AI runtime
reads the ai Settings namespace and swaps the adapter when the provider
comes from env or a stored Settings UI value. The provider setting has no
default, so an unset provider never masks boot-time auto-detection. memory is
not a Settings value: the Settings UI does not offer it, saving it is refused,
and OS_AI_PROVIDER=memory is reported and ignored. Settings values resolve as:
env (`OS_<NAMESPACE>_<KEY>`) > stored Settings UI value > defaultThat means OS_AI_PROVIDER=openai plus OS_AI_OPENAI_BASE_URL=... wins over
both the Settings UI and the boot-time provider auto-detection. ObjectStack
does not read unprefixed settings override names such as AI_PROVIDER or
AI_OPENAI_BASE_URL.
For example, a third-party OpenAI-compatible provider can be deployment-locked without using the Settings UI:
OS_AI_PROVIDER=openai
OS_AI_OPENAI_API_KEY=sk-...
OS_AI_OPENAI_MODEL=your-model
OS_AI_OPENAI_BASE_URL=https://your-provider.example.com/v1Provider credentials keep their upstream names. ObjectStack does not rename
OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, or
AI_GATEWAY_* to OS_*.
OpenAI-compatible base URLs. Use
OS_AI_OPENAI_BASE_URLwithOS_AI_PROVIDER=openai, configure the same fields in Settings → AI, or pass an explicit adapter in code. Do not rely onOPENAI_BASE_URLas a platform-level environment variable.
MCP Server
Enable this to make the app you built AI-operable: with the MCP server on, an
MCP client — Claude Code, Claude Desktop, Cursor, or a local model — connects to your
running app and gets a generated tool surface over your objects and actions
(query_records, run_action, …), bound to the caller's principal and governed by the
same RBAC / RLS as the Console. No custom tooling, no separate API. See
Actions as Tools for the tool set.
The HTTP surface and the long-lived stdio transport are separate switches
(they used to share one, which let =true silently attach an unscoped transport —
see the note below):
os start # HTTP MCP served at /api/v1/mcp by default
OS_MCP_SERVER_ENABLED=false os start # opt out of the HTTP MCP surface
OS_MCP_STDIO_ENABLED=true OS_MCP_STDIO_API_KEY=osk_... os start # start the local stdio transport as that key's identity| Variable | Type | Default | Description |
|---|---|---|---|
OS_MCP_SERVER_ENABLED | boolean | true | The MCP HTTP surface (/api/v1/mcp) is a core capability and defaults on. Set false to disable it (the endpoint answers 404 to a caller with an API key or token and 401 to an anonymous one, and the Connect-an-Agent page disappears). |
OS_MCP_STDIO_ENABLED | boolean | false | Auto-start the long-lived stdio transport at boot. Opt-in and stricter than the HTTP surface. Requires OS_MCP_STDIO_API_KEY — stdio runs as that key's identity with RLS/FLS/tenant applied; if the key is missing or invalid, boot fails closed (stdio refuses to start). See ADR-0101. |
OS_MCP_STDIO_API_KEY | string | — | The osk_... API key the stdio transport runs as. Resolved through the same verify chain as the HTTP/REST surfaces, so reads are scoped to that identity's permissions. Mint one from the Connect an AI Assistant page — the avatar menu or Account → AI Assistant for any signed-in user, Setup → Overview for platform admins — or POST /api/v1/keys. For full authority, mint a key on a platform-admin or dedicated service identity — there is deliberately no system/unscoped bypass. |
OS_MCP_SERVER_NAME | string | objectstack | Server name advertised to MCP clients. |
OS_MCP_SERVER_TRANSPORT | enum | stdio | stdio | http. Use http (Streamable HTTP) for a remote client; stdio for a local one. |
Deprecated (one release): OS_MCP_SERVER_ENABLED=true also used to auto-start
the stdio transport — overloading the HTTP switch, so setting it to "make sure MCP
is on" silently attached the unscoped stdio bridge. That trigger still works but now
logs a deprecation warning; use OS_MCP_STDIO_ENABLED=true instead.
OS_MCP_SERVER_ENABLED=false only ever gated HTTP and is unaffected.
Search
Pinyin recall for $search (ADR-0098): with the switch on, every object's
display/name field gets a hidden, platform-maintained companion column storing
full pinyin + initials ("张伟" → "zhangwei zw"), so lookup pickers, list
quick-search and ⌘K match zhangwei / zw against CJK names — transparently,
with no client or object changes.
os start # auto-on when the stack's i18n config lists any zh-* locale
OS_SEARCH_PINYIN_ENABLED=true os start # force on regardless of locales
OS_SEARCH_PINYIN_ENABLED=false os start # force off (e.g. a zh-locale stack that doesn't want the extra column)| Variable | Type | Default | Description |
|---|---|---|---|
OS_SEARCH_PINYIN_ENABLED | boolean | locale-derived | Pinyin search recall. When unset, the default derives from the stack's configured locales (i18n.defaultLocale / supportedLocales / fallbackLocale): any zh-* locale turns it on; an explicit value always wins. Gates both the compile-time __search companion column and the plugin-pinyin-search populate hooks, so there is no half-state. Off ⇒ no extra column, and pinyin-pro is never loaded. |
Coverage includes sys_user — the people picker finds users by pinyin with no
per-object configuration. Rows that predate the switch are backfilled automatically
on the first boot after it turns on (paged, idempotent); for runtime bulk imports
that bypassed write hooks, rebuildSearchCompanion (from
@objectstack/plugin-pinyin-search) recomputes the column on demand. See
Queries → Pinyin recall.
Marketplace & Metadata
| Variable | Type | Default | Description |
|---|---|---|---|
OS_MARKETPLACE_CACHE | enum | on | off disables the in-memory marketplace listing cache. |
OS_MARKETPLACE_PUBLIC_BASE_URL | url | — | Public base URL of the marketplace registry (proxied from this runtime when set). |
OS_ALLOW_UNMASKED_OBJECT_METADATA | boolean | false | Escape hatch for the metadata-plane field-level security mask (ADR-0106 D8). By default every object schema served by /meta and /metadata is projected onto the fields the calling user may read, so a field they cannot read does not appear at all — not its name, label, type, picklist options, formula, visibleWhen predicate, defaultValue, or the requiredPermissions capability guarding it; an action entry whose param binds such a field is answered as a name that does not exist. The same mask governs object visibility (ADR-0106, amended 2026-11-11): an object the calling user may not read is left out of every object list and is answered as an object that does not exist. Set to 1 to serve every object's full schema to every authenticated caller, including objects they may not read, as releases before ADR-0106 did. This changes disclosure only: the data plane still masks values and refuses forbidden writes either way, and the console reads field affordances from /auth/me/permissions, so toggling it never changes UI correctness. The REST layer also honours a per-server metadata.maskObjectFields: false; this variable is the deployment-wide knob and covers the runtime /metadata dispatcher, which has no REST config to read. |
OS_METADATA_WRITABLE | csv | — (none) | Comma-separated metadata type names (e.g. hook,job) granted a runtime escape hatch that treats them as allowEnvironmentOverlay: true for items no managed package ships: it opens runtime creation of a type whose registry entry allows none. It never opens an organization-scoped write: since ADR-0131 D6 the metadata protocol refuses every organization-scoped write with 403 NOT_OVERRIDABLE. It never opens an item a managed package ships: managed content is sealed (ADR-0131 D6), so an overlay or a removal of a shipped flow, object, field, permission set, position or any other type without an environment overlay is refused with 403 NOT_OVERRIDABLE whether the hatch is set or not. Customize managed content through its type's own route instead: an environment overlay for view, dashboard, report, translation and email_template; disable, or clone under a new name, for a flow; clone for a permission set. An overlay row this hatch wrote before over a managed item is kept at rest but not served: every read takes the package's definition, and boot names each such row, per type ([metadata_sealed_overlay_unserved]), with the two remedies — re-express the change as a new item under a new name, or delete the row. A stored fork of a packaged permission set is the one exception: the deployment does not boot while it holds one (ADR-0048); os migrate security-catalog-overlays lists such rows and, with --apply, deletes them, which restores the package's definition. A stored row over a managed item of the other types that merge overlays at read (position, page, app, dataset, book, tool, skill) can still be removed, but removing it changes nothing that is served: no read serves it, so the package's definition is already served. See ADR-0005. |
Multi-tenant / Cloud control plane
These variables are only meaningful when running in OS_MODE=cloud or against
the hosted ObjectOS Cloud control plane.
| Variable | Type | Default | Description |
|---|---|---|---|
OS_BASE_URL | url | — | Public base URL of this runtime, used in generated webhooks and links. |
OS_ROOT_DOMAIN | string | — | Root domain for multi-tenant subdomain routing (e.g. example.com). |
OS_ORGANIZATION_ID | string | — | Pin the runtime to a single organization id (per-process scope). |
OS_ENVIRONMENT_ID | string | — | Pin the runtime to a single environment id (per-process scope). |
OS_CLOUD_URL | url | https://cloud.objectos.ai | Base URL of the cloud control plane the CLI / runtime talks to. Set to off / local / none / disabled to disable cloud. |
OS_CLOUD_API_KEY | string | — | Shared secret authenticating runtime → cloud SSO handoffs. |
OS_CLI_CLIENT_ID | string | — | OAuth client id used by os login. |
OS_TOKEN | string | — | Personal access token used by the CLI in non-interactive contexts (CI). |
OS_PLATFORM_SSO | boolean | true | When false, fall back to local auth instead of the platform SSO handshake. |
OS_PROVISION_SYNC | flag | 0 | When 1, force synchronous provisioning of artifact kernels (slower boot, deterministic). |
OS_RUNTIME_PORT | number | — | Port the cloud control plane uses to reach this runtime (distinct from public OS_PORT). |
OS_PREVIEW_MODE | enum | — | Preview deployment routing mode. |
OS_PREVIEW_BASE_DOMAINS | csv | — | Comma-separated base domains used to resolve preview hostnames. |
Observability
| Variable | Type | Default | Description |
|---|---|---|---|
OS_OBS_EXPORTER | enum | noop | OpenTelemetry exporter. noop | console | json | otlp. noop (default) imposes no runtime cost. |
OS_OBS_SERVICE_NAME | string | objectstack | service.name resource attribute. |
OS_OBS_DEPLOYMENT_ENV | string | production | deployment.environment resource attribute. |
OS_OTLP_ENDPOINT | url | — | OTLP/HTTP collector endpoint. Required when OS_OBS_EXPORTER=otlp. |
OS_OTLP_HEADERS | csv | — | Comma-separated key=value pairs added to every OTLP export. |
OS_OTLP_FLUSH_MS | number | 10000 | OTLP batch flush interval. |
OS_TELEMETRY_CLIENT_ERROR_REPORTING_DSN | url | — | Error-reporting sink for the Console SPA, served as telemetry.errorReporting.dsn on /api/v1/runtime/config. Presence is the grant — unset means the Console sends nothing, and there is no separate permission flag. Set it here and nowhere else: the Console is consumed prebuilt, so this is the only place a self-hosting operator can configure it, and no frontend rebuild is involved. Refused loudly at mount when it is not an https://PUBLIC_KEY@HOST/PROJECT_ID URL, when it carries a secret after the public key (this payload is public to every browser), or when the runtime declared its control plane off (OS_CLOUD_URL=off). |
OS_TELEMETRY_CLIENT_ERROR_REPORTING_SEND_DEFAULT_PII | boolean | false | Attach IP address and User-Agent to client error events. Opt-in; an unrecognised value is refused at mount and stays off. Inert without a DSN. |
OS_TELEMETRY_CLIENT_ERROR_REPORTING_ENVIRONMENT | string | — | environment tag on client error events (production, staging, …). Unset lets the Console tag events with its own build mode. Inert without a DSN. |
OS_TELEMETRY_CLIENT_ERROR_REPORTING_TRACES_SAMPLE_RATE | number | 0.1 | Fraction (0–1) of Console transactions sampled for performance tracing. Out-of-range or unparseable values are refused at mount and fall back to the default. Inert without a DSN. |
OS_TELEMETRY_CLIENT_ERROR_REPORTING_REPLAY_SAMPLE_RATE | number | 0 | Fraction (0–1) of Console error sessions recorded as session replays. Off by default — replay records what the user did, so it is the deliberate choice of the deployment that wants it. Inert without a DSN. |
With several replicas declared over the Redis cluster driver (OS_CLUSTER_REPLICAS greater than 1 or OS_EXPECT_MULTI_NODE=true, with OS_CLUSTER_DRIVER=redis), the OTLP resource also carries service.instance.id, one value per replica: HOSTNAME-PID (the host name is the pod name on Kubernetes), or a random id when the host reports no name. The pid tells replicas apart only within one PID namespace: replicas that share a host name across containers (a fixed Compose hostname:, host-network containers) are each pid 1 and export the same id, so give each replica its own host name. It has no variable of its own. Every other boot exports service.name and deployment.environment only.
Tuning (advanced)
| Variable | Type | Default | Description |
|---|---|---|---|
OS_KERNEL_CACHE_SIZE | number | 32 | Max in-memory artifact kernels per process (cloud mode). |
OS_KERNEL_TTL_MS | number | 900000 | Idle TTL for cached kernels in ms. |
OS_ENV_CACHE_TTL_MS | number | 300000 | Env-record cache TTL in ms. |
OS_ARTIFACT_CACHE_TTL_MS | number | 300000 | Artifact-record cache TTL in ms. |
OS_ARTIFACT_FETCH_TIMEOUT_MS | number | 60000 | Timeout for remote artifact fetches. Only a positive value is honored — an unset, non-numeric, or 0 value falls back to the 60s default (pass fetchTimeoutMs: 0 in artifactSource config to actually disable the timeout). |
OS_SANDBOX_HOOK_TIMEOUT_MS | number | 250 | Default CPU-time budget for a sandboxed hook body (QuickJS, ADR-0102): how much VM-active time a body may burn — idle host-await time and a nested hook's own run are NOT charged. A loaded/slow host rarely needs to raise this now (it is not wall-clock), but the knob remains. Only a positive integer is honored; unset / non-numeric / non-positive keeps the 250ms default. A hook body's own declared timeoutMs still wins over this. |
OS_SANDBOX_ACTION_TIMEOUT_MS | number | 5000 | Default CPU-time budget for a sandboxed action body (QuickJS). Same resolution rules as the hook variant above (positive integer only; an action body's own timeoutMs still wins). |
OS_SANDBOX_WALL_CEILING_MS | number | 30000 | Wall-clock ceiling (ADR-0102) — the backstop that cuts a hook/action body stuck on a host call that never settles (which burns no CPU, so the CPU budget alone would never fire). The effective ceiling is max(this, cpuBudget), so it can never cut a body still inside its CPU budget. Positive integer only; unset keeps 30s. |
OS_LOCALIZATION_CACHE_TTL_MS | number | 30000 | Staleness bound, in milliseconds, for the cross-request cache of a workspace's reference localization (timezone / locale / currency, read from sys_setting) — leg C of #11633. 0 means off, a real path that restores the uncached query pattern exactly. Unlike OS_AUTHZ_GRANTS_CACHE_TTL_MS (which is off by default) this one ships on, because its invalidation is synchronous and in-process rather than TTL-bound: a localization settings change, a write to sys_setting or sys_platform_setting (the tables the answer is read from), and a non-write bump of the engine write epoch each retire a cached answer immediately. A write to any other object does not. So the TTL only bounds what none of these seams can see — a write made on another replica with no cluster bridge attached at all: neither the metadata.mutated channel's receipt path (applyRemoteMetadataMutation calls bumpWriteEpoch, #13609) nor the authz.invalidated bridge, both of which bump this same epoch when attached. ⚠️ A malformed value reads as 0 (off), the opposite arm from the grants variable and deliberately so: there 0 is also the default, whereas here folding 3OOO (letter O) into the default would hand you a longer window than the one you were setting. Deployment config only — never a settings row, because sys_setting is the table this cache caches. |
OS_METADATA_OVERLAY_CACHE_TTL_MS | number | 30000 | Staleness bound, in milliseconds, for the cross-request cache of the sys_metadata overlay rows read inside getMetaItems (the list read) and getMetaItem (the served by-name read the REST API-exposure gate makes on every /data request) — leg D of #11633. 0 means off, a real path that restores the uncached query pattern exactly. Ships on, for the same reason as OS_LOCALIZATION_CACHE_TTL_MS: invalidation is synchronous and in-process, because every sys_metadata write goes through the engine, whose middleware retires the entry when the write's statement completes, before the next read. Outside a transaction that is the commit. Inside an engine transaction it is earlier than the commit: a read that lands between the statement and the commit can keep the pre-commit rows until the next sys_metadata write or the TTL. A write to any other object does not retire it; a non-write bump of the engine write epoch retires it wholesale. What is cached is the overlay ROW SET only — never the merged answer — so the SchemaRegistry, the MetadataService and the artifact table are re-consulted on every call, cached or not, and the read-side registry hydration keeps running on a cache hit. The TTL therefore bounds one thing: a write made on another replica with no cluster bridge attached at all — neither the metadata.mutated channel's own receipt path (applyRemoteMetadataMutation calls bumpWriteEpoch right after registry convergence, #13609) nor the authz.invalidated bridge, either of which retires this entry the moment it is attached and fires. ⚠️ A malformed value reads as 0 (off) — same arm and same reason as OS_LOCALIZATION_CACHE_TTL_MS. Deployment config only, never a settings row. |
OS_METADATA_COMPILE_CACHE_TTL_MS | number | 30000 | Bound, in milliseconds, for the per-environment cache of compiled item answers (ADR-0156): the served item read (getMetaItem) of an app, object, view, page or dashboard, which the app bundle (GET /api/v1/meta/app/:appId/bundle) and the item reads make. 0 means off, a real path: the read is the uncached one, the same reads in the same order. Only the caller-independent answer is cached; the per-caller gate, field mask, translation and ETag are computed on every request. A local change is seen at once: the cache keeps the change counter of every source it reads (the sys_metadata overlay generation, the schema registry's revision and objectRevision, the metadata service's revision) and drops every entry when one moves; a source without its counter makes it decline. When the bound passes it confirms before it recompiles, with one reading of what this process cannot see (a digest of every sys_metadata row's identity, state, version, checksum and updated_at, not the bodies, which moves on any insert, delete or bookkeeping change including an older updated_at from a clock that is behind, and each metadata loader's own change mark: the file loader stats the directories and files its reads touched), once per bound however many requests cross it; unchanged, the entries stand for another bound, never past 10 bounds from when each was compiled; unreadable, nothing is renewed. Each confirmation also retires the overlay row cache, so the recompile reads the rows as they are now. The bound is therefore how long another replica's write with no cluster bridge, or a file created, removed or edited under a running process, can stay unseen; a file edit no stat can tell apart (same size, within the file system's time grain), or a write that bypasses the engine and changes a stored body while leaving version, checksum and updated_at as they were, is seen within 10 bounds. ⚠️ A malformed value reads as 0 (off). Deployment config only, never a settings row. |
OS_INLINE_SEED_BUDGET_MS | number | 8000 | Time budget for synchronous seed execution at boot before deferring to a worker. |
OS_TENANT_AUDIT | flag | 1 | Set to 0 to silence the tenant-isolation audit warnings emitted by the SQL driver. |
Legacy aliases
Some env vars accept a legacy alias for compatibility. Ecosystem-standard names (e.g. DATABASE_URL, AUTH_SECRET, BETTER_AUTH_*, PORT, CORS_*, MCP_SERVER_*) are permanently accepted and no longer warn. ObjectStack's own former names are deprecated — prefer the canonical OS_*.
Removed in 11 (rename required):
OS_MULTI_TENANT→OS_MULTI_ORG_ENABLED,OBJECTSTACK_METADATA_WRITABLE→OS_METADATA_WRITABLE,AUTH_BASE_URL/OS_AUTH_BASE_URL→OS_AUTH_URL.
| Canonical | Legacy |
|---|---|
OS_PORT | PORT |
OS_DATABASE_URL | DATABASE_URL |
OS_AUTH_URL | BETTER_AUTH_URL |
OS_AUTH_SECRET | BETTER_AUTH_SECRET, AUTH_SECRET |
OS_ROOT_DOMAIN | ROOT_DOMAIN |
OS_CORS_ENABLED | CORS_ENABLED |
OS_CORS_ORIGIN | CORS_ORIGIN |
OS_CORS_CREDENTIALS | CORS_CREDENTIALS |
OS_CORS_MAX_AGE | CORS_MAX_AGE |
OS_AI_MODEL | AI_MODEL |
OS_MCP_SERVER_ENABLED | MCP_SERVER_ENABLED |
OS_MCP_SERVER_NAME | MCP_SERVER_NAME |
OS_MCP_SERVER_TRANSPORT | MCP_SERVER_TRANSPORT |
OS_HOME | OBJECTSTACK_HOME |
OS_DEV_CRYPTO_KEY | OBJECTSTACK_DEV_CRYPTO_KEY |