Getting started

Quickstart

One command brings up a disposable estate, runs the real causal chain, and removes only what it created.

Before you start

Toolchain

Python 3.11–3.13 (3.12 recommended) and uv.

Docker

Docker with Compose !override support, and enough memory for the DataHub quickstart profile.

The estate binds host ports 13306, 14319, 15432, 18080, 19002, 19092, and 19200. Every one has a CLI override if it is already occupied.

This is a live estate

The flagship demo downloads the commit-pinned official DataHub Core v1.6.0 quickstart and starts real containers. It needs internet access for any upstream artifact or image it does not already have cached.

Run the whole chain

Install dependencies

Sync the workspace with every extra, so the DataHub, Actions, and PostgreSQL paths are all available.

Shell

uv sync --all-extras

Run the flagship demo

This downloads the pinned quickstart, starts it on isolated ports with PostgreSQL 16, waits for health, builds and inspects the replay sandbox, runs the causal chain, validates every proof boundary, and writes a raw-free report.

Shell

uv run --all-extras python -m examples.flagship_demo \
  --allow-live \
  --output .glassbox/flagship/one-command-report.json

Read the report

The report is raw-free by construction: digests, governed URNs, reason codes, and verification results only.

Shell

cat .glassbox/flagship/one-command-report.json

By default the estate is torn down when the run finishes. Pass --keep-estate to leave it up and explore DataHub and the console against live state.

What actually happened

This is one connected chain, not a replay fixture:

An instrumented agent run emitted OTLP spans, which the compiler turned into a canonical, signed receipt with a resolved dependency set.
The receipt registered in transactional state and published a governed DataHub projection, verified by direct entity readback.
A real schema field changed in DataHub. The Action consumed the change, built a content-addressed campaign, and a declarative rule pack classified the affected decision as material.
The exact receipt the live Action quarantined became the source of a fingerprint-authorized corrected bundle.
The corrected evidence digest replaced the affected action input, and the new decision was produced inside a source- and schema-bound hardened container.
DataHub read back both receipts plus their immutable supersession relation before the incident resolved.

Negative control

The same run exercises an unrelated-field change that must not invalidate the decision. A proof that only ever fires positively is not a proof.

Smaller checks

You do not need the full estate to see the core contracts work.

Verify a receipt with no DataHub at all

Shell

uv run glassbox-dbom verify tests/fixtures/dbom/valid-read-only.json

Verify against operator authority

A self-contained signature proves key possession, not authorization. For production authority, validate the operator registry and verify against it:

Shell

uv run glassbox-dbom verify-policy /etc/glassbox/trusted-signers.json
uv run glassbox-dbom verify receipt.json \
  --signer-trust-policy /etc/glassbox/trusted-signers.json \
  --json

Inspect the DataHub probe without writing

Shell

uv run glassbox-datahub-probe plan

Targeted proofs

Each of these runs one boundary against a live estate and writes its own sanitized evidence report.

bash

export GLASSBOX_STATE_POSTGRES_DSN='postgresql://...'
uv run python -m examples.end_to_end_receipt --allow-live

The Kafka proof deliberately injects an action failure, exhausts the synchronous commit retry window, forces exact same-offset redelivery, and takes a same-group recovery commit — then re-verifies a completed campaign with no additional DataHub write.

Read the architecture guide for the five steps in context, or open Connections to wire GlassBox into your own DataHub estate.