Skip to content
VB-OSVB-OSVB-OS Docs

Boundary Deployments in VB-OS

A deployment connects a compiled boundary version to an environment. When evidence arrives for evaluation, the engine uses the boundary version from the active deployment for that boundary in the target environment.

Deployment Model

Section titled “Deployment Model”

Each deployment records:

  • Boundary: the boundary being deployed (boundary_id)
  • Boundary version: the specific compiled version being deployed
  • Environment: where this version is active (e.g., development, staging, production)
  • Status: PENDING_APPROVAL, ACTIVE, SUPERSEDED, ROLLED_BACK, REJECTED, or CANCELLED

Only one deployment per boundary per environment can be ACTIVE at any time. This is enforced at the platform level with a unique constraint, not just application logic.

Creating a Deployment

Section titled “Creating a Deployment”

Deploy a boundary version to an environment:

deployment = client.deployments.create(
    project_id="PROJECT_ID",
    environment_id="ENVIRONMENT_ID",
    boundary_version_id="VERSION_ID",
)

When the target environment has approval_required=true, the deployment is created in PENDING_APPROVAL status and must be explicitly approved before becoming ACTIVE.

When a new deployment becomes ACTIVE in an environment that already has an active deployment for the same boundary, the previous deployment transitions to SUPERSEDED status atomically.

Approval Workflow

Section titled “Approval Workflow”

Environments can require approval before a deployment becomes active. When approval_required is enabled on the environment:

  1. The deployment is created in PENDING_APPROVAL status
  2. An authorized user reviews and approves, rejects, or cancels the deployment:
    • Approve → transitions to ACTIVE
    • Reject → transitions to REJECTED (terminal)
    • Cancel → transitions to CANCELLED (terminal)

When approval_required is not enabled, deployments are created directly in ACTIVE status.

Deployment Lifecycle

Section titled “Deployment Lifecycle”
┌──────────────────┐
│ PENDING_APPROVAL │ ◄── When approval_required=true
└──────┬───────────┘
       │
  ┌────┼──────────┐
  ▼    ▼          ▼
┌────────┐ ┌────────┐ ┌──────────┐
│ ACTIVE │ │REJECTED│ │CANCELLED │
└───┬────┘ └────────┘ └──────────┘
    │
┌───┴───────┐
▼           ▼
┌───────────┐ ┌────────────┐
│ SUPERSEDED│ │ ROLLED_BACK│
└───────────┘ └────────────┘
  • PENDING_APPROVAL → ACTIVE: the deployment is approved
  • PENDING_APPROVAL → REJECTED: the deployment is rejected
  • PENDING_APPROVAL → CANCELLED: the deployment is cancelled
  • ACTIVE → SUPERSEDED: a newer version is deployed to the same environment for the same boundary
  • ACTIVE → ROLLED_BACK: the deployment is explicitly rolled back

SUPERSEDED, ROLLED_BACK, REJECTED, and CANCELLED are terminal states. A deployment in a terminal state cannot become ACTIVE again: to restore a previous version, create a new deployment with that version.

Immutability

Section titled “Immutability”

Deployment records are append-only. The only permitted mutations are the terminal status transitions (ACTIVE → SUPERSEDED, ACTIVE → ROLLED_BACK). No other fields can be modified after creation.

Environments

Section titled “Environments”

Environments are isolated scopes within a project. Each environment has its own:

  • Active deployment
  • API keys scoped to that environment
  • Evaluation history

Typical environments: development, staging, production.

Promotion

Section titled “Promotion”

Promoting a boundary from one environment to another means creating a new deployment in the target environment with the same boundary version. The platform tracks which version is active in each environment.

Promotion requires an explicit boundary version ID to prevent TOCTOU (time-of-check-time-of-use) races. You cannot promote “the latest”: you must specify the exact version.

Next Steps

Section titled “Next Steps”