Skip to content
VB-OSVB-OSVB-OS Docs

Create a Verification Boundary in VB-OS

This guide walks through creating a boundary from scratch: writing the VBL, compiling it, and deploying it to an environment.

1. Define Your Requirements

Section titled “1. Define Your Requirements”

Before writing VBL, identify:

  • What action does this boundary authorize? (e.g., payment, deployment, agent action)
  • What evidence is needed to make the decision?
  • What conditions must the evidence satisfy?
  • What should be prohibited? (e.g., sensitive data that should never enter the pipeline)

2. Write the VBL

Section titled “2. Write the VBL”

Create a boundary file. This example authorizes a payment:

boundary_id: payment-authorization
version: 1
scope: production


# Evidence requirements
require_evidence: transaction_amount
require_evidence: account_balance
require_evidence: risk_score
require_type: transaction_amount: integer
require_type: account_balance: integer
require_type: risk_score: integer


# Provenance: risk score must come from the internal engine
require_provenance: risk_score: internal_risk_engine


# Prohibitions: no SSN in the workload
prohibit_evidence: social_security_number


# Predicates (all must pass, conjunctive evaluation)
predicate: sufficient_funds: account_balance >= transaction_amount
predicate: risk_acceptable: risk_score <= 75
predicate: amount_within_limit: transaction_amount <= 50000

3. Create the Boundary via API

Section titled “3. Create the Boundary via API”

The boundary_ref must match the pattern ^B_[A-Z0-9_]{3,48}$ (e.g., B_PAYMENT_AUTHORIZATION):

from vbos import VBOSClient


client = VBOSClient(api_key="YOUR_API_KEY")


boundary = client.boundaries.create(
    project_id="PROJECT_ID",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
    name="Payment Authorization",
    description="Authorizes payment transactions based on balance, risk, and limits",
    dsl_source=open("payment-authorization.vbl").read(),
)

The create call includes the dsl_source containing the VBL. Compilation validates the VBL syntax, checks for undefined references, and produces the initial boundary version. If compilation fails, the error response includes the specific syntax or semantic issue.

4. Update and Submit New Versions

Section titled “4. Update and Submit New Versions”

To revise a boundary after creation, update its draft and submit for review:

client.boundaries.update_draft(
    project_id="PROJECT_ID",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
    dsl_source=open("payment-authorization-v2.vbl").read(),
)


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

5. Deploy

Section titled “5. Deploy”

Deploy the compiled version to an environment:

deployment = client.deployments.create(
    project_id="PROJECT_ID",
    environment_id="ENVIRONMENT_ID",
    boundary_version_id=version["id"],
)

The boundary is now active. Verification requests to this environment will evaluate against this boundary version.

6. Verify

Section titled “6. Verify”

Test with a sample workload:

result = client.verify(
    workload={
        "transaction_amount": 15000,
        "account_balance": 42000,
        "risk_score": 35
    },
    project="my-project",
    boundary_ref="B_PAYMENT_AUTHORIZATION",
)


print(result.decision)  # "ASSERT"

Next Steps

Section titled “Next Steps”