Getting Started

Docker Compose (recommended)

The fastest way to run AI Governance Control Plane locally is with the Docker Compose stack. It starts the Keycloak IDP, REST API, Studio, and Neo4j in a single command:

# Clone Repository
git clone https://gitlab.com/bhanuj-ai/ai-governance-oss.git
cd ai-governance-oss

# Optional for Docker Compose; required for host-local commands below.
uv sync

# Create the development-only configuration files. Do not commit them.
cp .env.platform.example .env.platform
cp keycloak-postgres/.env.keycloak.example keycloak-postgres/.env.keycloak
cp console/.env.local.example console/.env.studio

./servers.sh

The stack starts:

• Keycloak IDP on http://localhost:18080 (the OSS local stack)
• REST API on http://localhost:8000
• Studio on http://localhost:3000
• Neo4j on bolt://localhost:7687
• SeaweedFS Filer on http://localhost:8888 for local dataset artifact inspection
• AI Governance Control Plane MCP Stdio (MCPO) on http://localhost:8001/docs
• AI Governance Control Plane MCP Streamable HTTP Server on http://localhost:8002/mcp

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

10-Minute Local Tour

Use the seeded local environment to learn the product before configuring a provider credential or creating your own assets. This is a read-only orientation: it shows the evidence path without changing your runtime.

1. Open Studio at http://localhost:3000 and select the default organization and project.
2. Open Assets to see governed prompts, models, datasets, and evaluator providers.
3. Open Experiments, choose a seeded experiment, and inspect its candidates, evaluation runs, item-level results, comparison, and leaderboard.
4. Open Policies Engine to inspect the release-gate policy, its active version, priority-ordered rules, and simulation trace.
5. Open Decisions and review the persisted outcome, explanation, evidence graph, lineage, and audit context.

The mental model is: assets → candidate → evaluation evidence → policy → governance decision. Read How AI Governance Platform Works alongside this tour for the ownership boundary.

First Governed Path

Once the local stack is healthy, use the guided walkthrough as the first success criterion. It follows the same public REST APIs used by Studio and producers, then returns links to inspect the resulting records.

uv run ai-governance walkthrough governed-replay

No bearer token export is needed: local startup configures the walkthrough service identity automatically. Read the Governed Replay Walkthrough for the expected steps, replay submission option, manifest, and recovery behavior.

Demo Data and Reseeding

Demo data is created automatically by default. To reseed it without deleting local state, use the generated local walkthrough credentials to obtain a short-lived token. The token stays in the shell and is not printed or written to a file.

set -a
. ./.env.oauth.generated
set +a

AI_GOVERNANCE_DEMO_TOKEN="$(uv run python -c '
from ai_governance.oauth import access_token_from_environment
token = access_token_from_environment()
assert token, "AI_GOVERNANCE_OAUTH_* credentials are required"
print(token)
')"

curl --fail-with-body -X POST http://localhost:8000/api/v1/ontology/demo/seed \
  -H "Authorization: Bearer ${AI_GOVERNANCE_DEMO_TOKEN}"
unset AI_GOVERNANCE_DEMO_TOKEN

To reset all local SQLite, Neo4j, and SeaweedFS data instead, run docker compose down -v followed by ./servers.sh. Normal docker compose down preserves local data.

Local Development Without Docker

AI Governance Control Plane uses Python 3.12+ and uv for dependency management:

# Clone Repository
git clone https://gitlab.com/bhanuj-ai/ai-governance-oss.git
cd ai-governance-oss

# Installs Dependencies
uv sync

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

# Starts Studio
cd console
pnpm install
pnpm build
pnpm start

# Starts MCP Server
uv run ai-governance-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:18080 (the OSS local stack)
• REST API on http://localhost:8000
• Studio on http://localhost:3000
• Neo4j on bolt://localhost:7687
• SeaweedFS Filer on http://localhost:8888 for local dataset artifact inspection
• AI Governance Control Plane MCP Stdio (MCPO) on http://localhost:8001/docs
• AI Governance Control Plane MCP Streamable HTTP Server on http://localhost:8002/mcp

Authentication & Startup

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

./servers.sh
# or, for local Python development
./servers-local.sh

Login with KEYCLOAK_ADMIN_USERNAME and KEYCLOAK_ADMIN_PASSWORD.

This is the Keycloak administrator login

These credentials open the Keycloak administration console in themaster realm. They are not the credentials used by a person connecting to Studio or the native MCP endpoint. For local Studio and VS Code MCP sign-in, use the studio user and theAI_GOVERNANCE_STUDIO_PASSWORD value inkeycloak-postgres/.env.keycloak.

bash

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

  KEYCLOAK_ADMIN_USERNAME=admin
  KEYCLOAK_ADMIN_PASSWORD=admin

  KEYCLOAK_URL=http://keycloak.localhost:18080
  KEYCLOAK_HTTP_PORT=18080
  KEYCLOAK_MANAGEMENT_PORT=19000
  KEYCLOAK_PROXY_HEADERS=xforwarded

  # The OSS local stack uses keycloak.localhost:18080 consistently.

  AI_GOVERNANCE_SERVICE_CLIENT_SECRET=secret
  AI_GOVERNANCE_MCP_CLIENT_SECRET=mcp-secret
  AI_GOVERNANCE_WALKTHROUGH_CLIENT_SECRET=walkthrough-secret
  AI_GOVERNANCE_ADMIN_PASSWORD=password

Use the configured Keycloak hostname consistently

The OSS stack publishes Keycloak on port 18080. Studio and the API use http://keycloak.localhost:18080 as the issuer hostname; the Keycloak administration console is available at http://localhost:18080. Do not mix the previous 8080 URLs with the OSS configuration.

Below screen shows the auto configured clients for the AI Governance control plane realm.

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

Go to Organizations. Grant the AI Governance Control Plane 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:8000/docs. This is the AI Governance Control Plane REST API for Swagger and REST-only clients:

Try open http://localhost:8001/docs. This is the MCPO OpenAPI proxy for Swagger and REST-only clients:

Each tool maps to a REST permission. `platform_operator` covers operational permissions such as`job.list` and `evaluation.metrics`. Membership and role administration require their specific permissions; use `organization_admin` only when that elevated access is intentional.

To connect an MCP-aware client such as VS Code, usehttp://localhost:8002/mcp instead of the Swagger URL. See the native Streamable HTTP guide for the Keycloak sign-in and first safe tool call.

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:

docker compose up -d neo4j

Configure the repository:

export AI_GOVERNANCE_GRAPH_URI=bolt://localhost:7687
export AI_GOVERNANCE_GRAPH_USER=neo4j
export AI_GOVERNANCE_GRAPH_PASSWORD=ai-governance-local-password
export AI_GOVERNANCE_GRAPH_DATABASE=neo4j

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

uv add neo4j

Studio

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

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

Run Studio locally:

cd console
pnpm install
pnpm dev

Studio reads the API base URL from NEXT_PUBLIC_AI_GOVERNANCE_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

• AI_GOVERNANCE_ENV=local and AI_GOVERNANCE_AUTH_MODE=keycloak
• AI_GOVERNANCE_POLICY_REPOSITORY=sqlite with a writable SQLite path
• NEXT_PUBLIC_KEYCLOAK_URL and the AI Governance Control Plane realm/client settings
• Keycloak available at http://keycloak.localhost:18080

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 AI_GOVERNANCE_WORKER_HEARTBEAT_STALE_SECONDS; set AI_GOVERNANCE_AUTO_SEED_DEMO_DATA=false when testing an empty environment.

Troubleshooting

• Missing environment variable: create the three required Compose files from their templates before running ./servers.sh. For host-local API or MCP work, also copy .env.local.example to .env.local; Uvicorn does not load those files automatically.
• Issuer mismatch: use one Keycloak hostname consistently in Studio, the API, and token validation. Local browser flows normally use keycloak.localhost:18080; Docker service-to-service calls use the configured container/network address.
• MCPO on port 8001 returns 401: verify the ai-governance-mcp client secret and regenerate .env.mcp.generated with the actor-discovery helper.
• Native MCP on port 8002 returns 401: reconnect the MCP client and complete the Keycloak browser login as studio. A 403 means login succeeded, but the signed-in actor lacks the required membership or organization/project role.
• Seed data appears missing: confirm AI_GOVERNANCE_AUTO_SEED_DEMO_DATA=true. The manual seed endpoint requires a JWT; use the short-lived-token command in Demo Data and Reseeding.
• Port already in use: stop the existing process or change the published host port before starting Compose. Do not remove unrelated Docker containers to resolve a local port conflict.