Local Development Setup

This guide walks you through setting up the complete Claw GRC development environment on your local machine.

Prerequisites

Tool	Version	Purpose
Docker	24+	PostgreSQL, infrastructure services
Go	1.24+	API Gateway, Compliance Engine
Python	3.13+	Security Engine, Agent Protocol
Node.js	22+	Frontend (Next.js)
golang-migrate	Latest	Database migrations

Installing Prerequisites

# macOS (Homebrew)
brew install go python@3.13 node
brew install golang-migrate

# Verify versions
go version       # go1.24+
python3 --version # Python 3.13+
node --version    # v22+

Quick Start

The fastest way to get everything running:

# Clone the repository
git clone https://github.com/onefrequency/claw-grc.git
cd claw-grc

# Install all dependencies (Go, Python, Node)
make setup

# Start all infrastructure (PostgreSQL, etc.)
docker compose up -d

# Run database migrations
make migrate

# Seed compliance data (11 frameworks, 1,026 controls)
make seed

# Start all services in the foreground
make dev

After startup, the services are available at:

Service	URL	Description
Frontend	http://localhost:3000	Next.js web application
API Gateway	http://localhost:8080	Authentication and routing
Compliance Engine	http://localhost:8081	Frameworks, controls, evidence
Security Engine	http://localhost:8082	Assessments, findings, scans
Agent Protocol	http://localhost:8083	Agents, MCP, trust scoring
PostgreSQL	localhost:5433	Database (user: claw, db: clawgrc)

Database

Connection Details

Parameter	Value
Host	localhost
Port	5433
User	claw
Password	clawgrc_dev_password
Database	clawgrc

Connecting Directly

# Via psql
psql -h localhost -p 5433 -U claw clawgrc

# Remember to set RLS context before querying tenant tables
SELECT set_config('app.current_org', '00000000-0000-0000-0000-000000000001', true);
SELECT * FROM agents;

Migrations

# Apply all pending migrations
make migrate

# Rollback last migration
make migrate-down

# Check current migration version
make migrate-status

# Create a new migration
make migrate-create NAME=add_new_table

# Force version after a failed migration
make migrate-force V=17

Seed Data

# Seed compliance data (idempotent - safe to re-run)
make seed

The seed data includes:

• 11 compliance frameworks (SOC 2, ISO 27001, NIST 800-53, etc.)
• 1,026 framework controls
• Unified control taxonomy with cross-framework mappings
• Evidence requirements for each unified control

Dev organization UUID: 00000000-0000-0000-0000-000000000001

Running Individual Services

Frontend Only

cd apps/web
npm run dev
# Available at http://localhost:3000

Go Services

# API Gateway
cd apps/api-gateway && go run ./cmd/server/

# Compliance Engine
cd apps/compliance-engine && go run ./cmd/server/

Python Services

# Security Engine
cd apps/security-engine
python -m uvicorn app.main:app --reload --port 8082

# Agent Protocol
cd apps/agent-protocol
python -m uvicorn app.main:app --reload --port 8083

Running Tests

# All tests
make test

# Go tests (single service)
cd apps/api-gateway && go test ./...
cd apps/compliance-engine && go test ./...

# Go single test
cd apps/api-gateway && go test -run TestHealthHandler ./internal/handlers/

# Python tests
cd apps/security-engine && python -m pytest
cd apps/agent-protocol && python -m pytest

# Python single test
cd apps/security-engine && python -m pytest tests/test_assessments.py -k test_create

# Frontend tests
cd apps/web && npx vitest run
cd apps/web && npx vitest run --reporter verbose src/lib/api.test.ts

Linting

# All services
make lint

# Individual
cd apps/api-gateway && go vet ./...
cd apps/security-engine && python -m ruff check .
cd apps/web && npx eslint . --quiet

Environment Variables

In development mode (ENVIRONMENT=development), authentication is bypassed. The API Gateway passes through all requests with a default development identity.

Key environment variables:

Variable	Default	Description
ENVIRONMENT	development	Set to production for auth enforcement
DATABASE_URL	host=localhost port=5433...	PostgreSQL connection string
COMPLIANCE_ENGINE_URL	http://localhost:8081	Compliance Engine URL
SECURITY_ENGINE_URL	http://localhost:8082	Security Engine URL
AGENT_PROTOCOL_URL	http://localhost:8083	Agent Protocol URL

Pre-Push Hook

The repository includes a pre-push hook that runs before allowing a push to the remote:

1. Go vet and tests for Go services
2. Python linting and tests for Python services
3. TypeScript type checking and Vitest for the frontend

All checks must pass before the push is allowed. To build the frontend for type checking, use:

cd apps/web && NODE_ENV=production npx next build

info

NODE_ENV=production is required for Next.js builds. Without it, the build fails with misleading errors.

Troubleshooting

Database Connection Issues

If you cannot connect to the database:

# Check if Docker containers are running
docker compose ps

# Restart just the database
docker compose restart postgres

Port Conflicts

If a port is already in use, check for conflicting processes:

lsof -i :8080  # API Gateway
lsof -i :8081  # Compliance Engine
lsof -i :8082  # Security Engine
lsof -i :8083  # Agent Protocol
lsof -i :5433  # PostgreSQL

Migration Issues

If a migration fails and leaves the database in a dirty state:

# Check the current version and dirty flag
make migrate-status

# Force the version to the last successful migration
make migrate-force V=17

# Re-run migrations
make migrate