Runtime Bundle

Overview

Org in a Box now treats runtime config as a staged artifact instead of a live config file. Provider rows in Postgres are the desired state, bun orginabox runtime apply promotes the staged bundle, and the sandbox only consumes the applied bundle.

flowchart LR
  A[Provider rows in Postgres] --> B[Stage runtime bundle]
  B --> C[/runtime/staged]
  C --> D[bun orginabox runtime apply]
  D --> E[/runtime/applied]
  E --> F[Sandbox reads applied bundle]
  F --> G[Prompt resolves applied model]
  G --> H[Explicit providerID and modelID]

State Layers

Desired state

Desired state lives in Postgres and includes:

• provider identity
• encrypted credentials
• base URL
• preferred flag
• default model

Staged state

The staged bundle is the latest generated runtime snapshot. It is safe to inspect before activation and can exist even when the applied bundle is older.

Applied state

The applied bundle is what the sandbox actually uses. Chat, session prompts, and runtime status checks should treat applied state as the source of truth.

Bundle Contents

The runtime bundle includes:

• manifest.json for revision and timestamp metadata
• runtime.json for the Orginabox-native runtime document
• auth.json for the sandbox adapter
• opencode.jsonc for the generated sandbox config

The base sandbox config stays provider-agnostic. Provider-specific behavior comes from the applied bundle, not from a checked-in opencode.jsonc default.

Apply Flow

1. A provider or model change is saved.
2. Orginabox stages a new runtime bundle from the DB state.
3. bun orginabox runtime status shows whether the staged and applied revisions differ.
4. bun orginabox runtime apply promotes the staged bundle to applied state.
5. The sandbox restarts and reads only the applied artifacts.

Prompt Routing

Orginabox-originated turns resolve against the applied runtime before they call into the sandbox. That means:

• staged changes do not affect live chat
• model selection does not depend on a boot-time default
• agent profile overrides still win when they point at a provider that exists in the applied bundle

Operational Checks

• Use bun orginabox runtime status when a provider change does not seem to affect chat.
• Use bun orginabox runtime apply after provider imports, credential updates, or default-model changes.
• If runtime apply fails, fix the provider row first and re-run the apply step.