KAVACHKAVACH
v2.0.1

Getting Started

This guide starts the Kavach API and Studio with Docker Compose, then shows how to run your first evaluation via REST or MCP.

Docker Compose (recommended)

The fastest way to run Kavach locally is with the Docker Compose stack. It starts the KeyCloak IDP, REST API, Kavach Studio, and Neo4j in a single command:

bash
# Clone Repository
git clone https://github.com/thisisbhanuj/Kavach.git
cd Kavach

# Install Dependencies
uv sync

./kavach.sh

The stack starts:

  • KeyCloak IDP on http://localhost:8080
  • REST API on http://localhost:8000
  • Kavach Studio on http://localhost:3000
  • Neo4j on bolt://localhost:7687
  • Kavach MCP Stdio (MCPO) on http://localhost:8001/docs
  • Kavach MCP Streamable HTTP Server on http://localhost:8002/

The local API starts with demo ontology data, a release-gate policy, governance decisions, representative jobs, and MCP audit data. Set KAVACH_AUTO_SEED_DEMO_DATA=false to disable startup demo seeding.

Data Persistence

The Compose stack uses named volumes for SQLite and Neo4j data. Normal docker compose down preserves data; use docker compose down -v to start fresh.

Local Development Without Docker

Kavach uses Python 3.12+ and uv for dependency management:

bash
# Clone Repository
git clone https://github.com/thisisbhanuj/Kavach.git
cd Kavach

# Installs Dependencies
uv sync

# Starts Platform & MCP Stdio
./kavach-local.sh

# Starts Studio
cd console
pnpm install
pnpm build
pnpm start

# Starts MCP Server
uv run kavach-mcp --transport streamable-http --host 127.0.0.1 --port 8002

This loads .env.local and starts the local dependency flow. If you invoke Uvicorn directly, export the variables from .env.local first; Uvicorn does not automatically load .env.platform or .env.local.

  • KeyCloak IDP on http://localhost:8080
  • REST API on http://localhost:8000
  • Kavach Studio on http://localhost:3000
  • Neo4j on bolt://localhost:7687
  • Kavach MCP Stdio (MCPO) on http://localhost:8001/docs
  • Kavach MCP Streamable HTTP Server on http://localhost:8002/

Authentication & Startup

Use the repository startup scripts so Keycloak, tenant bootstrap, the REST API, MCPO, and Studio start in dependency order.

bash
./kavach.sh
# or, for local Python development
./kavach-local.sh
Keycloak
→
Actor discovery
→
REST API
→
MCPO
→
Studio

Login with KEYCLOAK_ADMIN_USERNAME and KEYCLOAK_ADMIN_PASSWORD.
bash

  # .env.keycloak
  POSTGRES_DB=keycloak
  POSTGRES_USER=keycloak
  POSTGRES_PASSWORD=keycloak

  KEYCLOAK_ADMIN_USERNAME=admin
  KEYCLOAK_ADMIN_PASSWORD=admin

  KEYCLOAK_HTTP_PORT=8080
  KEYCLOAK_MANAGEMENT_PORT=9000
  KEYCLOAK_PROXY_HEADERS=xforwarded

  # For LOCAL
  KEYCLOAK_HOSTNAME=http://localhost:8080
  # For Docker
  # KEYCLOAK_HOSTNAME=http://keycloak.localhost:8080

  KAVACH_SERVICE_CLIENT_SECRET=secret
  KAVACH_MCP_CLIENT_SECRET=mcp-secret
  KAVACH_ADMIN_PASSWORD=password
Below screen shows the auto configured clients for the KAVACH realm.

Start the Kavach Studio http://localhost:3000.
and log in:

Kavach Studio home page should look like below:

Go to Organizations. Grant the Kavach Administrator & MCP service account the required tenant roles under Organization → Access. typically, MCP will need additional ORGANIZATION ADMIN at Organisation scope & VIEWER role at project scope.

Try open http://localhost:8001/docs. You will see the MCP Tools Server over HTTP:
Each tool maps to a REST permission. `platform_operator` covers operational permissions such as`mcp_audit.readaddit` and `job.read`. Membership and role administration require their specific permissions; use `organization_admin` only when that elevated access is intentional.

Neo4j Setup

Neo4j server is already a part of the docker and local stack, if used. Hence this step is not required.

For the governance ontology graph, start Neo4j Community Edition:

bash
docker compose up -d neo4j

Configure the repository:

bash
export KAVACH_GRAPH_URI=bolt://localhost:7687
export KAVACH_GRAPH_USER=neo4j
export KAVACH_GRAPH_PASSWORD=kavach-local-password
export KAVACH_GRAPH_DATABASE=neo4j

The Neo4j adapter imports the Neo4j Python driver only when constructed. If the driver is not installed:

bash
uv add neo4j

Kavach Studio

Studio server is already a part of the docker and local stack, if used. Hence this step is not required.

Kavach Studio is a Next.js application providing a governance console for policies, evaluations, decisions, the ontology graph, and MCP audit.

Run Studio locally:

bash
cd console
pnpm install
pnpm dev

Studio reads the API base URL from NEXT_PUBLIC_KAVACH_API_BASE_URL (defaults to http://localhost:8000). Graph canvas colors can be adjusted with NEXT_PUBLIC_GRAPH_INPUT_COLOR, NEXT_PUBLIC_GRAPH_OUTPUT_COLOR, and NEXT_PUBLIC_GRAPH_ROOT_COLOR.

Local Configuration Checklist

  • KAVACH_ENV=local and KAVACH_AUTH_MODE=keycloak
  • KAVACH_POLICY_REPOSITORY=sqlite with a writable SQLite path
  • NEXT_PUBLIC_KEYCLOAK_URL and the Kavach realm/client settings
  • Keycloak available at http://keycloak.localhost:8080

Running a first evaluation

Submit an evaluation via the REST API. Here we use the built-in mock provider:

bash
curl -X POST http://localhost:8000/api/v1/evaluations \
  -H "content-type: application/json" \
  -d '{
    "provider_name": "mock",
    "workflow_id": "claim-validation",
    "workflow_name": "Claim Validation",
    "execution_id": "exec-1",
    "input": {"question": "Was the claim valid?"},
    "final_state": {"answer": "The claim appears valid."},
    "metric_specs": [{"name": "answer_relevance"}]
  }'

Verifying Worker Health

Startup demo seeding registers representative job and evaluation workers in the configured persistence backend. Open Studio Home and confirm the Job Workers health component reports active workers. Worker health is based on the worker_heartbeat registry, not only on jobs currently in progress. Configure the stale threshold with KAVACH_WORKER_HEARTBEAT_STALE_SECONDS; set KAVACH_AUTO_SEED_DEMO_DATA=false when testing an empty environment.

Creating a governance decision

Evaluate a subject against a policy, attaching the evaluation result as evidence. Kavach returns a deterministic decision with the governing policy version and a reason.

bash
curl -X POST http://localhost:8000/api/v1/decisions/evaluate \
  -H "content-type: application/json" \
  -d '{
    "subject_type": "agent_execution",
    "subject_id": "execution-2048",
    "policy_id": "production-ai-policy",
    "evidence_ids": ["eval-result-981"]
  }'

Next step

Continue with the REST control plane tutorial to explore the full API surface.

Troubleshooting

  • Missing environment variable: use ./start-local.sh or source .env.local; do not assume Uvicorn loads platform configuration files.
  • Issuer mismatch: use one Keycloak hostname consistently in Studio, the API, and token validation. Local browser flows normally use keycloak.localhost:8080; Docker service-to-service calls use the configured container/network address.
  • MCP returns 401: verify the kavach-mcp client secret and regenerate .env.mcp.generated with the actor-discovery helper.
  • MCP returns 403: authenticate successfully, then grant the service account membership and the required organization/project role in Studio → Organization → Access.
  • Seed data appears missing: confirm KAVACH_AUTO_SEED_DEMO_DATA=true. To reset local Docker data, run docker compose down -v and start again.
  • Port already in use: stop the existing Studio/API process or change the published port before starting Compose again.