Air-gapped Deployment

Air-gapped deployment is for customer networks where ObjectOS cannot call a hosted control plane or public package registries at runtime.

What to ship

An offline release bundle should contain:

The container image and artifact mount follow the same conventions as a standard Docker deployment; only the network posture differs.

Runtime mode

Use file-backed mode: point ObjectOS at a local artifact and a customer-managed business database, and leave the cloud control plane unset.

OS_ARTIFACT_FILE=/artifacts/objectstack.json
OS_BUSINESS_DB_URL=file:/var/lib/objectos/data.db
# Leave OS_CLOUD_URL unset to run fully offline

ObjectOS resolves every request to the packaged project and loads the artifact from disk. With OS_CLOUD_URL unset, no calls are made to a hosted control plane.

Network expectations

ObjectOS does not need public internet access in this mode. Customer network rules should allow only:

• inbound HTTP/HTTPS from the approved ingress or load balancer;
• outbound database traffic to the customer-managed business database;
• outbound traffic to explicitly configured integrations such as SMTP, object storage, webhook targets, or identity providers.

Authentication

If the customer uses OIDC/SSO, the identity provider must be reachable from the air-gapped network. If not, use local email/password auth or an identity provider hosted inside the same network.

Installing additional packages

A running air-gapped instance can take additional packages without any catalog connectivity — hand the compiled artifact to the install CLI and it is sent inline and merged into the live kernel (no restart):

os package install ./dist/objectstack.json --runtime https://os.internal.example \
  --email admin@example.com --password …

The manifest is cached on the runtime host under .objectstack/installed-packages/ and re-registers on every boot.

Upgrade process

Treat artifacts as immutable:

1. Import the new ObjectOS image.
2. Place the new artifact beside the previous artifact.
3. Update the mount or environment variable to point at the new artifact.
4. Restart ObjectOS.
5. Roll back by restoring the previous image tag or artifact path.

See Upgrade and Backup for the full procedures these steps summarize.