Velvet

Outcome assurance for autonomous agents

Velvet is a local, self-hosted system for teams moving agents from impressive demos to consequential business actions. It maps every declared route to a protected outcome, tests whether controls hold across those routes, gates supported execution paths, and preserves evidence that can be verified offline.

Authorize the route. Assure the outcome.

New: protected refund contract. Commit exact-command authorization, order limits, a shared budget, operation identity and journal evidence in one PostgreSQL transaction. Closure and refunds share the same lock. A separate database identity exports a signed snapshot for offline replay and reconciliation. Read the contract and reproduce it · Inspect the recorded PostgreSQL evidence. This is a single-database reference ledger; external payment rails are outside its claim.

Explore the product site · Review the design-partner pilot · Read the outcome portfolio guide

Related MCP server: gov-mcp

Your agent blocked the tool. Did it block the outcome?

Most agent controls watch a named tool or API route. An agent can still reach the same business effect through a browser, a second API, a database, a queue, a webhook, delegated credentials, or a human operator.

ShadowPath tests the effect, not just the route. It is Velvet's open-source assessment wedge: the fastest way to show why a route-level deny is not yet an outcome-level assurance claim.

The committed hermetic fixture protects customer.disable. The canonical tool is denied before dispatch. ShadowPath then exercises eight equivalent routes and independently reconciles the customer state:

That verdict means the route-level control reported success while the prohibited effect still occurred. It does not mean a named vendor failed: this is a synthetic local fixture designed to make the measurement reproducible.

Inspect the result · Read the v0.4 benchmark spec · Add an effect path · Replay it live

Run it

See the committed result and generate shareable evidence immediately:

uvx --from git+https://github.com/paulchum/velvet-rope.git velvet-rope shadowpath demo

That command runs the public GitHub source directly—no clone or global install.

The instant demo is explicitly a replay of the committed hermetic run. It writes exact SVG, PNG, HTML, Markdown, and badge artifacts under reports/shadowpath/share/; it never presents the replay as a fresh measurement.

Execute the Playwright-backed fixture from source when you want a fresh run:

git clone https://github.com/paulchum/velvet-rope.git
cd velvet-rope
uv sync --dev
uv run maturin develop
uv run playwright install chromium
uv run velvet shadowpath demo --execute

Or execute the same fixture in the browser-ready container:

docker run --rm -v "$PWD/reports:/reports" \
  ghcr.io/paulchum/shadowpath:latest

The executed demo writes the machine-readable result and a Markdown report under reports/shadowpath/. It acknowledges the fixture's expected breach for the process exit code; the recorded verdict remains CONTROL_FALSE_SUCCESS.

For CI or publishable measurements, keep strict exit codes:

uv run velvet shadowpath run \
  --output-dir reports/shadowpath-strict \
  --allow-dirty --json

Exit 3 means a prohibited effect was observed. Remove --allow-dirty for a clean, commit-bound benchmark artifact.

Test your own effect

Scaffold an executable effect inventory and independent observer:

uvx --from git+https://github.com/paulchum/velvet-rope.git velvet-rope shadowpath init my-effect
cd my-effect
uvx --from git+https://github.com/paulchum/velvet-rope.git velvet-rope shadowpath run \
  --project shadowpath.json \
  --output-dir reports/shadowpath

The starter intentionally demonstrates a false success: the protected route is denied while three equivalent routes still reach the prohibited state. Replace its four small adapter operations with your local reset, dispatch, and independent observation logic, then add every path your agent can reach.

Follow the 15-minute guide · Add ShadowPath to GitHub Actions · Browse integration recipes

Roll protected outcomes into a portfolio

Once one effect project is useful, group many projects into an estate-level result with owners and criticality:

uv run velvet shadowpath portfolio \
  --manifest shadowpath-portfolio.json \
  --output-dir reports/outcome-portfolio

The portfolio runner preserves every underlying effect result and writes one conservative status: ASSURED, DEGRADED, or ACTION_REQUIRED. The status is bounded by the outcomes, routes, and observers declared in the manifest; it does not infer coverage for missing paths.

Read the outcome portfolio guide

The eight routes

Each route starts from a fresh fixture state. The benchmark records dispatch evidence, observes the substrate directly, and distinguishes attributed effects from effects the system under test never saw.

What Velvet is

Velvet is an Apache-2.0 agent outcome-assurance and authorization project with three related jobs:

1. Test the whole effect surface. ShadowPath measures whether a control prevents a prohibited outcome across equivalent routes, inventories those routes, and detects effects after execution.

2. Control and prove execution. The Rust MCP proxy and Python SDK admit, block, or escalate consequential actions before dispatch, then emit evidence that can be verified offline.

3. Roll up protected outcomes. Outcome portfolios group user-owned effect projects into a conservative estate-level status without hiding the underlying route evidence or claim boundary.

The open core includes:

• a Rust MCP proxy for stdio and Streamable HTTP;

• deterministic policy evaluation and signed policy bundles;

• single-use Execution Permits bound to request, policy, schema, identity, audience, and proof lineage;

• signed Execution Receipts and a tamper-evident binary ledger;

• Vault Merkle proofs, Signed Tree Heads, retention records, and offline verification;

• approval, replay, attestation, evidence-pack, and claims-pack helpers;

• signed, expiring Certified Decision verdicts for bounded retirement claims.

Try the admission path

After the source setup above, run the zero-Docker MCP fixture:

uv run velvet demo --output-dir reports/demo --json

Or inspect the pieces independently:

uv run velvet mcp demo run --output-dir reports/mcp-proxy --json
uv run velvet ledger verify \
  --ledger reports/mcp-proxy/velvet_ledger.vledger --json
uv run velvet mcp conformance --json

Build the proxy container locally:

docker build -t velvet-rope-proxy -f deploy/mcp_proxy/Dockerfile .
docker run --rm velvet-rope-proxy conformance

How to contribute something that matters

The highest-leverage contribution is not another abstract policy rule. It is a new way to reach the same effect.

• Add an equivalent route to the ShadowPath fixture.

• Bring a real open-source control adapter and measure it without loaded claims.

• Improve independent reconciliation for a new effect class.

• Reduce setup friction on Linux, macOS, or Windows.

• Turn an edge case into a tiny reproducible fixture.

Start with the effect-path contribution guide or open the Add an effect path issue form.

If ShadowPath changes how you think about agent tool controls, star the repo and send it to the person responsible for your agent's last irreversible action.

Trust boundaries

Velvet Rope does not claim to be a universal agent-safety solution. The committed ShadowPath result executes synthetic local routes against a hermetic service. It is not a live competitor evaluation. Strong execution guarantees still depend on complete route inventory, enforcement at every relevant substrate, trustworthy reconciliation, protected signing keys, and correct deployment.

Also not claimed:

• legal compliance, audit outcomes, insurance coverage, or pricing effects;

• a production arbitrary-code sandbox;

• hard spend guarantees without provider hard caps and single-writer atomic accounting;

• immutable storage or formal certificates for every agent action.

See the public claims policy, implementation status, and live-demo boundaries before making broader claims.

Development

uv run ruff check .
uv run mypy src tests
uv run pytest
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Architecture and evidence references live in docs/, with the Agent Authorization Benchmark under benchmarks/agent_authorization/.

Apache-2.0. Built in public; skeptical reproductions welcome.