ObjectOSDeployment
Run ObjectOS on your own infrastructure — the open Community image or the licensed Enterprise image, one runtime, one configuration contract, and what the license adds.
ObjectOS has two self-managed editions, and they deploy the same way. ObjectOS Community is the open-source runtime image; ObjectOS Enterprise is the licensed image, one edition with every Enterprise feature included. Both run the same runtime and read the same configuration: a database, an auth secret and a secret key. What differs is where the image comes from, how the app gets in, and what a license unlocks. Each page in this section is written once for both, and ends with an Enterprise adds section where the licensed image does more.
The two images
| Community | Enterprise | |
|---|---|---|
| Image | ghcr.io/objectstack-ai/objectstack, public | The licensed Enterprise image, from a private registry; your license comes with the registry credentials |
| Pin it by | The exact version tag (X.Y.Z), which matches the ObjectStack CLI inside, and its digest wherever the bytes must not change (why) | The image digest your release notes name |
| Architectures | linux/amd64 and linux/arm64 | linux/amd64 only |
| How the app arrives | Your compiled objectstack.json from os build: mounted, copied into your own image, or named by OS_ARTIFACT_URL. An empty runtime installs apps from the Console marketplace instead. | One of three run shapes: the app bundled in the image, a published artifact, or a published artifact composed with the image's enterprise plugins (below) |
| Variables you must set | OS_DATABASE_URL, OS_AUTH_SECRET, OS_SECRET_KEY (the image already sets OS_PORT=8080) | The same, plus OS_LICENSE_KEY and a deliberate OS_CLOUD_URL |
| Copyable configuration | The examples on these pages | The deploy bundle that ships with each release |
| What the license unlocks | — | In-product AI (AI Builder, "ask your data"), AI governance, hierarchy security, several organizations on one deployment, SCIM on by default, customer-managed keys, air-gapped operation. The kit runs one node today; high availability across several replicas is in development and not offered yet. |
Compare Editions has the full matrix. An app built on Community is ordinary ObjectStack metadata and runs on Enterprise unchanged.
Every deployment decides three things
| Decision | What it means |
|---|---|
| Which bytes run | Pin one exact image. A rolling tag such as latest can be re-pointed under you, and so can an exact version tag when that version is rebuilt; only a digest cannot. Keep the previous one: that is what a rollback is. |
| Where the configuration lives | Outside the image and the app. The database URL, the secrets and the deployment's identity are environment variables injected at runtime, never baked in. Environment Variables is the contract. |
| Which database | Production runs on PostgreSQL. With no OS_DATABASE_URL the runtime writes a SQLite file under its home directory, which suits one durable host and loses data on a container's ephemeral filesystem. |
How the app gets in
The Community image carries no app. You give it the artifact that
os build compiles, dist/objectstack.json, in one of three ways:
| Way | How | Use it when |
|---|---|---|
| Mount it | Mount the file at /srv/app/objectstack.json, where the image looks by default | You want no image build at all |
| Copy it into your own image | A two-stage Dockerfile FROM the official image | You ship one self-contained image per release |
| Name it by URL | OS_ARTIFACT_URL, with an optional #sha256= integrity pin | You want app upgrades to be an environment change and a restart |
Docker shows all three. With no artifact at all, the runtime boots an empty kernel, and apps are installed from the Console marketplace.
Guides
- Docker — run the image, configure it, put it behind a proxy, upgrade it.
- Kubernetes — the same image on an orchestrator, and the properties to preserve.
- Air-gapped — Enterprise only: air-gap as a license mode, and the combinations refused at startup.
Without a container runtime, the same artifact runs under os start on a
host with Node.js 22 — see
Run ObjectOS Community locally.
Enterprise adds
Two more decisions: license and cloud posture
| Decision | What it means |
|---|---|
| Which license | A license is part of the happy path, not an add-on. Some deployment shapes refuse to start without one. |
| Which cloud posture | Whether this runtime talks to a control plane. This is coupled to the license mode, and unsupported combinations are refused at startup rather than degrading quietly. |
The two are one decision in practice, and getting them wrong is a boot failure, not a slow leak. Air-gapped states the supported combinations in full — read it even if your site is connected, because it is the page that explains why the pairs are what they are.
The deploy bundle
Your release ships a deploy bundle: a Compose stack, environment templates for each supported shape, and a README with the exact commands for your version — including the registry reference, the digest, and the supply-chain verification steps.
These pages carry the decisions — why a digest, which license mode for which shape, what multi-node makes mandatory, what the runtime refuses. The bundle carries the values you copy. When the two ever seem to disagree, the bundle that shipped with your image is right: it is versioned with the runtime it configures.
Three run shapes
The Enterprise image can run the app three ways, and the choice affects what is available to you — it is not just a matter of packaging.
| Shape | The app comes from | Use it when |
|---|---|---|
| Config-authored | The image's own bundled application — the metadata authored in the image, plus anything installed into it | A single-organization deployment; the default the Compose stack configures, and the shape that needs no configuration. |
| Artifact-pinned | A published app artifact named by URL, resolved before any deployment config runs | You run one published app and want app upgrades to be an environment change and a restart, with no image rebuild. Note that the deployment's enterprise plugins do not load on this path. |
| Composed | A published app artifact composed with this deployment's enterprise plugins | Several organizations share one database. This is the hosted single-app SaaS shape — and it is air-gap-licensed only, enforced at startup. |
Each shape has its own environment template in the deploy bundle. Copy the one for your shape rather than adapting another: the templates differ in the values that decide posture, and those are exactly the values the runtime checks before it serves anything.
Cloud Connection
Link a self-hosted ObjectOS Community or Enterprise server to your ObjectOS Cloud organization with a one-time code, so its Marketplace shows your organization's packages — and what revoking or disconnecting removes.
Docker
Run ObjectOS with Docker — pin the image, set the three required variables, add PostgreSQL with Compose, wire the probes and the proxy, upgrade and roll back. The Enterprise image adds a private registry, verification and a license.