ObjectOSRuntime Configuration
Where the running app comes from, which database it uses, and the startup decisions a deployment has to declare.
Runtime configuration answers three questions:
- Where does the running app come from?
- Which database does it use?
- What is this deployment entitled to be — connected or disconnected, one organization or many?
This page is about the shape of those decisions. The variable names and their exact contracts are in Environment Variables; the values you copy are in the deploy bundle that ships with your release.
Where the app comes from
Exactly one source is in effect, and the deployment declares which.
| Mode | Use when | How the app arrives |
|---|---|---|
| Config-authored | The shipped shape: one app, evaluation, air-gapped, most production deployments | The runtime serves the metadata authored in the image, plus whatever has been installed into it |
| Artifact-pinned | The app is released on its own cadence, independently of the runtime image | One variable names a published artifact by URL. The image's own configuration is not loaded on this path |
| Composed | Several organizations behind the isolation wall, sharing one database, running a published app | The same artifact reference, consumed from the deployment's own configuration so the enterprise plugins load with it. Air-gap licensed only, and refused at startup otherwise |
Upgrading a published app is a change to the artifact reference plus a restart — no image rebuild. Rollback is the same operation with the previous URL, which only works if the previous object still exists with the same bytes. That is a property of how you publish, not of the runtime, so three rules go with the mode:
- Publish immutable, version-named objects. Never overwrite a published artifact and never publish to a moving name. A mutable name means the running app can change with no deployment event, makes rollback impossible, and destroys the audit answer to "what was running at 14:05".
- Give write access to the publishing pipeline only. An artifact store humans can write to is a production deploy path with no review on it.
- Pin the digest in production. The reference carries an optional integrity pin; with one, a mismatch refuses the boot and names the expected and the actual digest. Without one, the runtime boots whatever the host returned and cannot tell a republished artifact from a substituted one.
A file:// reference exercises the same path with no artifact host, which
makes it the right way to rehearse a deployment — the production command then
differs from the rehearsed one in exactly one place.
Migrations on the artifact path
"Upgrade the app" on this path is an environment change and a restart, with nobody at a terminal at the moment schema and metadata can first disagree. So this path — and only this one — applies safe schema changes automatically and refuses the boot on a destructive one, naming every change and the command that resolves it. Every other boot keeps the standing production policy, under which the schema is never altered automatically.
Startup decisions the runtime will not guess
Some configurations are checked when configuration is loaded and refused rather than degraded. A refusal prints a fatal error naming the settings that disagree, and exits.
- Licence mode and cloud posture are coupled. An ordinary licence is validated online against a control plane; an air-gap licence is verified locally with no network traffic. Pairing an ordinary licence with "no control plane" is impossible, not degraded, and is refused before any validation is attempted. Air-gapped carries the full matrix.
- Leaving the cloud posture unset is not "no cloud". Unset resolves to the public control plane. A deployment meant to talk to nobody has to say so explicitly.
- A multi-organization posture requires a licence, and makes two further decisions mandatory: what a new sign-up joins, and which AI agents are mounted. Declaring either available value is accepted; not deciding is not. A single-organization deployment sees neither check.
- A cluster driver makes one shared secret key mandatory on every replica. Without a cluster driver each replica mints its own; across replicas those would silently diverge, so the runtime refuses to start instead.
Connecting to a control plane
A control plane is what serves the marketplace catalog and validates an ordinary licence. Connecting is a binding, not a pasted credential: the deployment is bound to the control plane once, and the runtime persists the token it was issued and presents that on every later call. There is no deployment API key to distribute or rotate by hand.
A bound, cloud-connected deployment is still a single-environment deployment. Connecting to a control plane does not turn one deployment into many.
Database
In production, point the deployment at a managed database and remove the bundled database service from the stack. The bundled one exists so that a first run works; it is not a production posture, and container-local storage is not where business data belongs.
The driver is inferred from the connection URL's scheme. Override it explicitly only when the scheme cannot carry that information — an unsupported value fails rather than falling back to a guess.
The shipped stack runs schema migration as a one-shot step that completes before any application replica starts, so concurrent replicas never run schema changes against each other. Any other orchestrator has to reproduce that ordering. See Data Sources for declaring additional datasources, and Backup for the restore side.
Authentication secret
Sessions are signed from a base secret, and it must be identical on every replica. Rotating it invalidates every existing session, and it also orphans the stored signing key — so a rotation is a planned operation, not a configuration tweak — the deploy bundle's template states the one extra step a rotation needs. Keep the secret in a secret manager, never in an image.