Skip to content
VB-OSVB-OSVB-OS Docs

Manage VB-OS Boundary Versions

Version Lifecycle

Section titled “Version Lifecycle”

Each boundary version follows this lifecycle:

Create → Compile → Deploy → (Supersede when next version deploys)

Versions are immutable after creation. To change a boundary, create a new version.

Create a New Version

Section titled “Create a New Version”

Update the draft with new VBL source and submit for review:

from vbos import VBOSClient


client = VBOSClient(api_key="YOUR_API_KEY")


client.boundaries.update_draft(
    project_id="PROJECT_ID",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
    dsl_source="""
boundary_id: payment-authorization
version: 2
scope: production


require_evidence: transaction_amount
require_evidence: account_balance


predicate: sufficient_funds: account_balance >= transaction_amount
""",
)


client.boundaries.submit(
    project_id="PROJECT_ID",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
)

Submission validates syntax, checks for undefined references, and produces the compiled version. Only approved versions can be deployed.

Diff Versions

Section titled “Diff Versions”

Compare two versions to see what changed:

diff = client.boundaries.diff(
    project_id="PROJECT_ID",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
    from_version_id="VERSION_A_ID",
    to_version_id="VERSION_B_ID",
)

List Versions

Section titled “List Versions”
versions = client.boundaries.versions(
    project_id="PROJECT_ID",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
)


for v in versions["items"]:
    print(f"v{v['version_number']}: {v['status']}")

Promote Across Environments

Section titled “Promote Across Environments”

Deploy the same version to multiple environments:

version_id = "COMPILED_VERSION_ID"


# Deploy to staging
client.deployments.create(
    project_id="PROJECT_ID",
    environment_id="STAGING_ENV_ID",
    boundary_version_id=version_id,
)


# After testing, deploy to production
client.deployments.create(
    project_id="PROJECT_ID",
    environment_id="PROD_ENV_ID",
    boundary_version_id=version_id,
)

Always use the explicit version ID. The version that was tested in staging is the same version deployed to production: no recompilation, no drift.

Immutability

Section titled “Immutability”

Once a version is compiled, its snapshot is immutable. The compiled boundary cannot be modified. This ensures:

  • Evaluations reference a specific, unchanging boundary
  • Replay uses the exact version from the original evaluation
  • Audit trails are tamper-evident

Next Steps

Section titled “Next Steps”