Getting Started with PRECINCT

Prerequisites

The following tools are needed to build and run the PRECINCT stack. Only the first three are required for the Docker Compose quickstart; the rest are needed only for Kubernetes deployment, policy testing, or manifest validation.

Option 1: Docker Compose (Recommended for First Run)

Docker Compose is the fastest way to get PRECINCT running. The entire stack (gateway, SPIRE, OPA, mock MCP servers, and observability) comes up with a few make commands.

Step 1: Clone the repository

git clone https://github.com/RamXX/agentic_reference_architecture.git
cd agentic_reference_architecture/POC

Step 2: Start the observability stack

make phoenix-up
# Phoenix UI available at http://localhost:6006

Optional indexed audit backend: make opensearch-up && make opensearch-seed (Dashboards at http://localhost:5601).

Step 3: Start the full PRECINCT stack

make up
# Gateway available at http://localhost:9090

Step 4: Run the E2E demo (28 test scenarios)

make demo-compose

Step 5: Explore

curl -s http://localhost:9090/health | jq .

Option 2: Kubernetes (Docker Desktop)

For a production-representative deployment, run PRECINCT on Kubernetes. Docker Desktop's built-in Kubernetes works out of the box.

Step 1: Enable Kubernetes in Docker Desktop

Open Docker Desktop, navigate to Settings → Kubernetes → Enable Kubernetes, and wait for the cluster to become ready.

Step 2: Deploy

cd POC
make k8s-up
# Gateway available at http://localhost:30090

Optional: deploy the Kubernetes OpenSearch extension with make k8s-opensearch-up once required TLS and credential secrets are provisioned in observability.

Step 3: Run E2E demo

make demo-k8s

Step 4: Tear down

make k8s-down

Your First Request

Once the stack is running, interact with the PRECINCT gateway directly. These examples use the Docker Compose endpoint (localhost:9090); substitute localhost:30090 if running on Kubernetes.

List available tools (authenticated)

curl -s http://localhost:9090/ \
  -H "Content-Type: application/json" \
  -H "X-SPIFFE-ID: spiffe://poc.local/agents/mcp-client/dspy-researcher/dev" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq .

Call a tool

curl -s http://localhost:9090/ \
  -H "Content-Type: application/json" \
  -H "X-SPIFFE-ID: spiffe://poc.local/agents/mcp-client/dspy-researcher/dev" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"tavily_search","arguments":{"query":"AI security"}},"id":2}' | jq .

Try without identity (should fail)

curl -s http://localhost:9090/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq .code

Verify Security Controls

Walk through each layer of the PRECINCT security model to confirm that all controls are active and enforcing correctly.

1. Identity: Send a request without a SPIFFE ID. The gateway returns spiffe_auth_required, confirming that unauthenticated requests are rejected at layer 3.
2. Authorization: Send a request with a valid but unauthorized SPIFFE ID. The gateway returns authz_policy_denied, confirming that OPA policy evaluation at layer 6 blocks the request.
3. DLP: Send a request body containing an AWS access key (e.g., AKIAIOSFODNN7EXAMPLE). The gateway returns dlp_credentials_detected, confirming that the DLP scanner at layer 7 blocks credential exfiltration.
4. Tool Registry: Request an unknown tool name. The gateway returns tool_not_in_registry, confirming that only registered and hash-verified tools may be invoked.
5. Rate Limiting: Send a burst of rapid requests. The gateway returns HTTP 429 Too Many Requests, confirming that per-identity token-bucket enforcement at layer 11 is active.
6. Audit: Check gateway logs for hash-chained JSONL audit events. Each event contains a unique decision ID and a cryptographic hash linking it to the previous event, providing tamper-evident audit trails.

Generate Compliance Evidence

PRECINCT includes built-in tooling for generating compliance artifacts, running security scans, and validating production readiness.

Full compliance report

make compliance-report

Security scans

make security-scan

Production readiness validation

make production-readiness-validate

Run Benchmarks

Measure the performance impact of the 13-layer middleware chain with the built-in benchmark suite.

make benchmark
# Shows: Go benchmarks, latency percentiles, per-middleware breakdown, load test

The benchmark output includes Go micro-benchmarks for each middleware layer, end-to-end latency percentiles (p50, p95, p99), per-middleware breakdown showing exactly where time is spent, and a load test that exercises the full stack under sustained throughput.

Explore the Codebase

The PRECINCT proof-of-concept lives in the POC/ directory. Here is a guide to the key paths.

Next Steps

Now that you have a running stack, dive deeper into the architecture, compliance mappings, and production deployment guides.

Get Help

• GitHub Issues: github.com/RamXX/agentic_reference_architecture/issues
• Full documentation: available in the repository docs/ directory.
• Architecture specification: precinct-reference-architecture.md in the repository root.