Environment Variables

Environment variables carry deployment-level decisions: which image is running, where the data lives, and what this deployment is entitled to be. Anything a tenant or an administrator should be able to change while the deployment is running belongs in system settings instead.

This page is the contract — what each variable decides, and what happens when two of them disagree. The Edition column says which image reads it:

• Both — the open Community image, ghcr.io/objectstack-ai/objectstack, and the licensed Enterprise image alike.
• Enterprise — only the Enterprise image, or the deploy bundle that ships with it.

On Community, Docker shows the values to set. On Enterprise, the values you copy live in the deploy bundle that ships with your release: an annotated template you copy to .env and edit. That template is pinned to your release; this page is not. Where the two differ, the template shipped with your image wins.

Naming. ObjectOS-owned variables use the OS_ prefix. A few pre-1.0 unprefixed names still work and emit a one-shot deprecation warning — see Legacy names. Two other groups are worth knowing before you reach for a name you remember: retired names, which are read by nothing or refuse the boot outright, and legacy names that still resolve.

The decisions every deployment makes

License and cloud posture

These two are a pair. Setting one without reading the other is the most expensive mistake on this page, because unsupported pairings are refused at startup rather than degraded.

On Community there is no license, so OS_CLOUD_URL decides only whether the deployment connects to a control plane. On Enterprise the two variables are a pair, and two consequences follow — both surprise people:

• Unset is not "off" — on either edition. An unset OS_CLOUD_URL resolves to the public control plane. It was never a neutral value — it selects the connected behaviour. A deployment meant to talk to nobody must say off out loud.
• An ordinary license with off is refused at startup, naming both variables. It is not a degraded state but an impossible one: an online license is validated by an exchange that needs a control plane, so with none configured the exchange is never made — not on this boot and not on a later one — and the grace window never starts, because grace runs from the last successful validation.

Air-gapped Deployment carries the full matrix of supported combinations and the reasoning behind the refusal.

Multi-organization deployments

A walled tenancy posture puts up the per-organization isolation wall. It is a licensed capability, and it makes three further decisions mandatory: the runtime refuses to start until each is declared. Declaring any available value is accepted; not deciding is not.

A single-organization deployment sees none of these checks. It may leave the last three unset: the first account to register becomes the platform administrator, unless OS_PLATFORM_OWNER_EMAIL names one, in which case that verified account does.

Multi-node

Multi-node is an Enterprise capability. A Community deployment runs one replica, and declaring more — OS_CLUSTER_REPLICAS above 1 — refuses the boot rather than run replicas on per-process locks. Scaling past one replica changes what is mandatory: a cluster driver, and the same OS_SECRET_KEY and OS_AUTH_SECRET on every replica.

OS_SECRET_KEY becomes required once a cluster driver is set. With no cluster driver each replica mints and persists its own key; across replicas those keys would silently diverge, so the runtime refuses to boot instead of serving with inconsistent crypto.

Running a published app

The runtime image and the app it serves are independent release axes: one variable names a published artifact, and upgrading the app is a change to that variable plus a restart — no image rebuild.

There is deliberately no companion variable for the integrity hash. The pin lives in the URL fragment, so there is one value to copy and one to rotate, and "URL updated, hash not" is not a state you can spell.

Publish to immutable, version-named objects, give the artifact host's write credential to your publishing pipeline only, and pin the digest in production. Those three rules are what make rollback — the same operation as upgrade, with the older URL — actually work.

Runtime services

Observability

Export is opt-in. The exporter defaults to noop, so a deployment emits nothing until you select one — setting an endpoint alone does nothing.

Data-contract escape hatches

ObjectStack 17.0 made the platform refuse values that break their declared contract, where it used to warn and accept them. These variables re-open the old behaviour temporarily, for an integration you cannot fix today. Each takes exactly 1; anything else leaves the strict behaviour on. The violation is still logged, so the drift stays visible.

Media and value shapes are checked strictly on a database the 17.x runtime created. A database upgraded from an earlier major is checked strictly only once the matching migration has recorded its flag — see CLI → Data migrations. Do not reach for OS_DATA_VALUE_SHAPE_STRICT_ENABLED=1 to get there sooner: it turns strict checking on for every value class at once, whatever this deployment's data actually holds.

Pinning a system setting

System settings — the tenant- and administrator-editable ai, email, feature_flags and similar namespaces — can be pinned at the deployment level with a variable named OS_ plus the namespace plus the key, uppercased, with . and - replaced by _. For example ai.openai_base_url becomes OS_AI_OPENAI_BASE_URL, and feature_flags.ai_enabled becomes OS_FEATURE_FLAGS_AI_ENABLED. A pinned setting is read-only in Setup.

Google sign-in, configurable in Setup → Authentication, also reads GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET at the deployment level.

Retired names

These names appeared in earlier ObjectOS documentation. They are listed here so that a configuration file you inherited can be read and corrected — not so they can be used. Each is retired on both editions, except where its row says otherwise.

OS_CLOUD_API_KEY is not a variable a self-hosted deployment sets. It is the service credential the hosted cloud injects into runtimes it operates itself, and — separately — the bearer token os package publish uses to authenticate against a package catalog from CI (see Packages). A self-hosted deployment that connects to a control plane presents a runtime token minted when the deployment was bound to that control plane, not a key you paste into a file.

Legacy names

These still resolve on both editions, but the canonical name is preferred and the legacy one may be removed in a future major version.