VB-OS Quickstart: Your First Verification in 5 Minutes

This quickstart gets you from zero to a verified workload in under five minutes. You will:

1. Pick a starter template
2. Submit a sample workload
3. Receive your first ASSERT verdict
4. Submit a failing workload to see a DEFER verdict
5. Replay a past evaluation

No VBL authoring or connector setup is required: you start with a pre-built template and sample data. This aligns with the onboarding path: starter → sample workload → ASSERT → DEFER → replay.

Prerequisites

• A VB-OS account with an organization and project
• An API key scoped to an environment with an active deployment
• Python 3.9+ or Node.js 18+ (for SDK examples)

Install the SDK

Python

pip install "vb-os"

Node.js

npm install @vb-os/sdk

cURL

No installation needed: use cURL directly.

Step 1: Verify a Workload (ASSERT)

Submit a workload that satisfies all boundary conditions. The API returns a deterministic verdict.

Python

from vbos import VBOSClient

client = VBOSClient(api_key="YOUR_API_KEY_HERE")

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

print(result.decision)        # "ASSERT"
print(result.evaluation_id)   # UUID of the evaluation record
print(result.replay_id)       # UUID for replaying this evaluation

Node.js

import { VBOSClient } from '@vb-os/sdk';

const client = new VBOSClient({ apiKey: 'YOUR_API_KEY_HERE' });

const result = await client.verify({
  project: 'my-project',
  environment: 'development',
  boundary_ref: 'payment-authorization',
  workload: {
    transaction_amount: 15000,
    account_balance: 42000,
    risk_score: 35,
  },
});

console.log(result.decision);        // "ASSERT"
console.log(result.evaluation_id);   // UUID of the evaluation record
console.log(result.replay_id);       // UUID for replaying this evaluation

cURL

curl -X POST https://api.vb-os.org/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-project",
    "environment": "development",
    "boundary_ref": "payment-authorization",
    "workload": {
      "transaction_amount": 15000,
      "account_balance": 42000,
      "risk_score": 35
    }
  }'

The response includes the full evaluation breakdown:

{
  "decision": "ASSERT",
  "evaluation_id": "01912345-6789-7abc-def0-123456789abc",
  "replay_id": "01912345-6789-7abc-def0-123456789abd",
  "boundary_ref": "payment-authorization",
  "boundary_version": 1,
  "admissibility": {
    "status": "SATISFIED",
    "required": ["transaction_amount", "account_balance", "risk_score"],
    "present": ["transaction_amount", "account_balance", "risk_score"],
    "missing": []
  },
  "prohibitions": {
    "status": "SATISFIED",
    "prohibited": [],
    "detected": []
  },
  "predicate_results": {
    "sufficient_funds": { "passed": true, "expression": "account_balance >= transaction_amount" },
    "risk_acceptable": { "passed": true, "expression": "risk_score <= 75" },
    "amount_within_limit": { "passed": true, "expression": "transaction_amount <= 50000" }
  },
  "failure_reasons": []
}

Step 2: Trigger a DEFER

Submit a workload that violates a boundary condition to see what a DEFER looks like.

Python

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

print(result.decision)         # "DEFER"
print(result.failure_reasons)  # Shows which predicates failed

cURL

curl -X POST https://api.vb-os.org/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-project",
    "environment": "development",
    "boundary_ref": "payment-authorization",
    "workload": {
      "transaction_amount": 75000,
      "account_balance": 42000,
      "risk_score": 35
    }
  }'

The response shows exactly why the evaluation was deferred:

{
  "decision": "DEFER",
  "failure_reasons": [
    {
      "type": "PREDICATE_FAILED",
      "predicate": "sufficient_funds",
      "expression": "account_balance >= transaction_amount",
      "actual": null
    },
    {
      "type": "PREDICATE_FAILED",
      "predicate": "amount_within_limit",
      "expression": "transaction_amount <= 50000",
      "actual": null
    }
  ]
}

Two predicates failed: the transaction amount exceeds both the account balance and the per-transaction limit.

Step 3: Replay the Evaluation

Every evaluation is replayable. Use the replay_id from Step 1 to reproduce the original verdict.

Python

replay_result = client.evaluations.replay(
    project_id="PROJECT_ID_HERE",
    evaluation_id="EVALUATION_ID_HERE"
)

print(replay_result.decision)  # "ASSERT" -- identical to the original

cURL

curl -X POST https://api.vb-os.org/v1/projects/{project_id}/evaluations/{evaluation_id}/replay \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

The replay retrieves the original boundary snapshot and evidence from immutable storage, verifies integrity hashes, and re-executes the evaluation. The result is identical to the original.

What Just Happened

1. You submitted evidence (a workload) to a verification boundary
2. The engine checked admissibility (all required fields present), prohibitions (no prohibited fields), and predicates (all conditions met)
3. The engine returned a deterministic ASSERT or DEFER verdict
4. You replayed a past evaluation and got the same result

Next Steps

• Your First ASSERT: understand the ASSERT verdict in detail
• Your First DEFER: understand failure reasons and what they mean
• Replay Your Decision: learn how replay works and why it matters
• Core Concepts: deep dive into evidence, boundaries, and evaluations