Textbook 05 Install And Deploy CAVRA

Install And Deploy CAVRA

This chapter is the first practical path through CAVRA. It takes a new reader from a clean checkout to a visible blocked action, a verified evidence bundle, and the sandbox GUI.

The operating pattern is stable: install CAVRA, choose a policy pack, evaluate actions, generate evidence, and decide where enforcement belongs.

Repository Setup

Clone the public repository:

git clone https://github.com/Huzefaaa2/cavra.git
cd cavra

Install the Python package in editable mode for local development:

python -m venv .venv
source .venv/bin/activate
pip install -e .

If CAVRA is available from your Python package index, use an isolated CLI install instead:

pipx install cavra

For source development, keep the editable install. For daily CLI use, prefer pipx or a dedicated virtual environment so CAVRA dependencies do not mix with application dependencies.

Validate the CLI:

cavra version
cavra policy list

Five-Minute Tutorial: Block A Dangerous Agent Action

Start with the flagship demo:

cavra demo before-the-agent-acts

Expected decisions:

Attempted action	Expected CAVRA outcome
Read .env	Blocked
Modify iam/admin-role.tf	Requires approval
Run terraform plan	Allowed
Run terraform apply -auto-approve	Blocked
Use unknown filesystem MCP server	Blocked
Push directly to main	Blocked
Open a pull request	Allowed with attestation

Now evaluate one risky command directly:

cavra evaluate execute_command "terraform apply -auto-approve" --json

The decision payload tells you the action, target, policy mode, decision, reason, and evidence expectations. In a real agent workflow, the agent or wrapper should stop when the decision is block or requires_approval.

Evaluate a risky file write:

cavra evaluate write_file iam/admin-role.tf --json

Evaluate a direct protected-branch push:

cavra evaluate git_operation origin/main --json

Evaluate an unknown MCP tool path:

cavra evaluate mcp_tool_call unknown-filesystem --json

Generate And Verify Evidence

Create evidence after the demo:

cavra evidence bundle --output .cavra/evidence/latest
cavra evidence verify .cavra/evidence/latest

For signed verification, create a keypair and trust root first:

cavra evidence generate-keypair
cavra evidence trust-root .cavra/keys/evidence-ed25519-public.pem --key-id local-evidence-key
cavra evidence trust-bundle .cavra/keys/evidence-trust-root.json
cavra evidence bundle --output .cavra/evidence/latest --private-key .cavra/keys/evidence-ed25519-private.pem --key-id local-evidence-key
cavra evidence verify .cavra/evidence/latest --trust-root .cavra/keys/evidence-trust-root.json

The important learning is that CAVRA does not only say "allowed" or "blocked." It creates a record that can later support review, CI/CD checks, AISPM posture, or audit.

Local Evaluation Patterns

Use these commands as your first local test set:

cavra evaluate write_file iam/admin-role.tf --json
cavra evaluate execute_command "terraform plan" --json
cavra evaluate execute_command "terraform apply -auto-approve" --json
cavra evaluate git_operation origin/main --json

Use JSON output for automation and evidence workflows. Use cavra policy explain when the decision is surprising:

cavra policy explain execute_command "terraform apply -auto-approve"

Sandbox GUI

The public sandbox is a static UI under apps/sandbox-ui. Run it locally:

python -m http.server 5173 --directory apps/sandbox-ui

Open http://localhost:5173 and explore the dashboard, demo scenarios, evidence console, approvals, registry views, and AISPM pages.

Docker And Compose

The repository includes Docker examples for local evaluation and demo environments:

• docker-compose.yml
• docker/docker-compose.community.yml
• examples/docker/README.md

Use Docker when you want repeatable local startup or a shared demo environment. Use the Python editable install when you are modifying policy, CLI, or source behavior.

API Deployment

CAVRA includes a public API surface for decisions, policy packs, approvals, evidence, AISPM samples, and sandbox workflows. See API for endpoint families. A local deployment normally starts the API, configures policy and storage paths, then allows the sandbox UI or automation scripts to call the API.

CI/CD Deployment

CAVRA can be used in CI/CD to require policy decisions and evidence before merging or deploying. A typical flow is:

1. A pull request proposes a high-risk change.
2. CAVRA evaluates the change.
3. Required approvals are opened or verified.
4. Evidence is generated.
5. A CI required check verifies the evidence and attestation.

See GitHub Required Checks And CI/CD Enforcement and Evidence Hub And Attestation.

Example workflow files are available under:

• examples/github-actions/cavra-required-check.yml
• examples/github-actions/cavra-enterprise-enforcement.yml
• examples/gitlab-ci/cavra-required-check.gitlab-ci.yml

Enterprise Deployment

Enterprise deployment adds SSO, RBAC, tenant configuration, live connectors, private policy packs, report delivery, and AISPM live ingestion. Use Enterprise Trial Self-Service Access, OIDC RBAC Deployment, Connector Execution Hooks, and AISPM Enterprise Live Ingestion as the main references.

Enterprise deployment models:

Model	Use when	Key work
Self-hosted control plane	You need private deployment and customer-controlled evidence stores.	Configure identity, policy registry, tenant audit store, connectors, and report delivery.
Docker or Compose	You need repeatable pilot or lab environments.	Pin images, mount policy/evidence paths, and keep secrets outside source control.
Kubernetes or Helm-style deployment	You need production-grade scheduling, ingress, secret management, and observability.	Add SSO/RBAC, persistent stores, network policy, connector credentials, and readiness probes.
Air-gapped or regulated environment	You need offline evidence, reproducible packages, or restricted network paths.	Use signed packages, offline trust roots, immutable storage, and export workflows.

Deployment Checklist

• Confirm edition and license boundary.
• Select policy packs.
• Configure evidence storage and trust roots.
• Configure approvals and break-glass rules.
• Configure agent and MCP trust registry entries.
• Add CI/CD enforcement where required.
• For Enterprise, configure tenant identity, connectors, SMTP or report provider settings, runtime workflows, and AISPM ingestion.
• Run readiness validators before production launch.

First Success Criteria

You have completed the first onboarding path when:

• cavra demo before-the-agent-acts shows blocked, approval-routed, allowed, and attested outcomes.
• cavra evaluate execute_command "terraform apply -auto-approve" --json returns a blocking decision under the starter policy.
• cavra evidence bundle creates an evidence directory.
• cavra evidence verify succeeds.
• The sandbox GUI opens and you can identify Dashboard, Evidence, Approval, Registry, and AI Posture areas.