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 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

Licence 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.

Two consequences follow, and both surprise people:

• Unset is not "off". 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 licence with off is refused at startup, naming both variables. It is not a degraded state but an impossible one: an online licence 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 two further decisions mandatory: the runtime refuses to start until each is declared. Declaring either available value is accepted; not deciding is not.

A single-organization deployment sees neither of the last two checks and may leave both unset.

Multi-node

Scaling past one replica changes what is mandatory.

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.

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.

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, but the canonical name is preferred and the legacy one may be removed in a future major version.