For AI agents: the documentation index is at /docs/interbox/llms.txt. A Markdown version of this page is available at /docs/interbox/ops/updating.md or by requesting it with the Accept: text/markdown header.
Interbox Docs

Updating the Engine

Interbox releases two artifacts cut from the same commit and versioned in lockstep: the engine image (healthsamurai/interbox on Docker Hub) and the SDK (@health-samurai/interbox on npm) your workspace is built against. Updating means moving the image to a new tag and keeping the workspace's SDK in a compatible range. Database migrations run automatically on boot.

Updating the engine (this page) is separate from updating your pipelines. Pipeline changes are a workspace edit the running engine picks up on its own by re-cloning and rebuilding — no image change. See Getting Started.

Move the image tag

The image tag is the engine version. Pre-GA the default is the moving edge tag; for production pin a released semver (e.g. 1.4.1).

Docker Compose — set INTERBOX_VERSION in .env, then pull and recreate:

# .env
INTERBOX_VERSION=1.4.1

docker compose pull
docker compose up -d

Kubernetes (Helm) — bump image.tag (or the chart's appVersion) and upgrade:

helm upgrade --install interbox healthsamurai/interbox \
  -n interbox --reuse-values --set image.tag=1.4.1

The rollout behavior (single replica, Recreate → a brief stop-then-start) is covered in Deployment; the value keys and pinning options (digest pin, pullPolicy) live in the chart's README.

Keep the workspace SDK compatible

This is the one update step unique to Interbox. At boot the engine loads your workspace and refuses to start if the workspace was built against an incompatible SDK — before it runs any pipeline, so you get a clear error up front instead of a confusing failure deeper in.

Compatible means the same npm caret (^) bucket: the same major version, or — while on 0.x — the same minor. So 1.3.0 ↔ 1.9.2 are compatible; 1.x ↔ 2.x, or 0.4 ↔ 0.5, are not.

Within a compatible bucket (a patch or minor bump on 1.x) the workspace needs no change — just move the image tag. When you cross the boundary, align the workspace's SDK and redeploy it:

interbox pin 1.4.1      # rewrites @health-samurai/interbox to ^1.4.1 in package.json
bun install

interbox pin with no argument reads $INTERBOX_VERSION, so one variable can pin both the image tag and the SDK dependency — see CLI.

You will know you got it wrong because the engine stops at boot with a message like:

engine/SDK version mismatch: this workspace is built against
@health-samurai/interbox 1.3.0, but this engine ships 2.0.0. They must share
the same major version (or the same minor while 0.x). Run `interbox pin 2.0.0`
and reinstall, or set INTERBOX_VERSION to an image matching SDK 1.3.0.

What happens on boot

Every start — an update included — the container:

  1. ensures its interbox database exists (unless you've told it the database is pre-created);
  2. applies any new migrations — idempotent, and forward-only;
  3. builds the workspace bundle and runs the SDK compatibility check above;
  4. starts the engine and API.

Because deployments run a single replica with a Recreate rollout, an update is a brief full stop-then-start, not a rolling one. MLLP senders reconnect and retry once the listener is back, and in-flight messages get the termination grace period to persist and ACK.

Rolling back

Interbox uses Drizzle Kit, which is forward-only: drizzle-kit generate emits only up-migrations and there is no rollback command, so there are no down-migrations to run. If an update applied a schema change, moving the image tag back runs the older engine against the newer schema, which it may not expect. So:

  • Prefer rolling forward — deploy a newer image tag that fixes the problem rather than reverting to the old one. A forward move keeps migrations additive; reverting fights the schema.
  • Roll the image tag back only when the version gap applied no migration (e.g. a same-series revert), or restore the database from backup alongside it.
  • Test upgrades in staging first — especially across a major version, where the workspace SDK moves too.

Last updated: