Skip to content

Getting Started with Fulcrum

Time to complete: 5 minutes

This guide takes you from zero to a running Fulcrum instance with your first policy enforced. By the end, you will have:

  • A fully operational Fulcrum stack running locally
  • A governance policy blocking unauthorized actions
  • An AI agent integrated via SDK
  • Visibility into execution traces

Prerequisites

Before starting, ensure you have:

Requirement Version Check Command
Docker Desktop 4.0+ docker --version
Docker Compose 2.0+ docker compose version
Node.js 18+ node --version
Python 3.9+ (optional) python --version
Go 1.24+ (optional) go version

System Requirements: - 4GB RAM minimum (8GB recommended) - 5GB available disk space - Ports 3001, 5432, 6379, 8080, 50051 available

Quick Start

Step 1: Clone and Start

# Clone the repository
git clone https://github.com/Fulcrum-Governance/fulcrum.git
cd fulcrum

# Start the full stack
./scripts/start-stack.sh

The startup script runs preflight checks, starts infrastructure (PostgreSQL, NATS, Redis), runs database migrations, and launches all application services. This typically takes 2-3 minutes on first run.

Step 2: Verify Services

Once startup completes, verify all services are healthy:

docker compose -f docker-compose.unified.yml ps

You should see these services running:

Service Port Purpose
fulcrum-server 50051 (gRPC), 8080 (REST) Core governance API
fulcrum-dashboard 3001 Web administration UI
fulcrum-postgres 5432 Primary database
fulcrum-nats 4222 Event streaming
fulcrum-redis 6379 Policy cache
fulcrum-grafana 3000 Metrics dashboards

Step 3: Open the Dashboard

Navigate to http://localhost:3001 to access the Fulcrum dashboard.

The dashboard provides: - Overview: Real-time metrics and system health - Policies: Create and manage governance rules - Traces: Inspect execution history and policy decisions - Approvals: Review pending human-in-the-loop requests - Settings: API keys and configuration

Create Your First Policy

Policies define the rules that govern AI agent behavior. Let's create a cost limit policy.

Option A: Using the Dashboard

  1. Navigate to Policies in the sidebar
  2. Click Deploy New Policy
  3. Select Cost Limit as the policy type
  4. Configure:
  5. Name: Dev Cost Cap
  6. Max Cost per Request: $0.10
  7. Action on Violation: DENY
  8. Click Deploy

Option B: Using the REST API

curl -X POST http://localhost:8080/api/v1/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dev Cost Cap",
    "policy_type": "cost_limit",
    "rules": {
      "max_cost_usd": 0.10,
      "action": "DENY"
    },
    "enabled": true,
    "priority": 100
  }'

Option C: Using gRPC

grpcurl -plaintext -d '{
  "name": "Dev Cost Cap",
  "policy_type": "cost_limit",
  "rules": {"max_cost_usd": 0.10, "action": "DENY"},
  "enabled": true
}' localhost:50051 fulcrum.governance.v1.PolicyService/CreatePolicy

Integrate Your First Agent

Choose your preferred SDK to add governance to your AI agent.

Python SDK

Install: 

pip install fulcrum-governance

Basic Integration: 

from fulcrum import FulcrumClient

# Connect to local Fulcrum
client = FulcrumClient(
    host="localhost:50051",
    api_key="dev-key"  # Optional in dev mode
)

# Wrap your agent execution
with client.envelope(workflow_id="my-support-bot") as env:
    # Check policy before executing
    if env.guard("send_email", input_text=user_message):
        # Allowed - proceed with action
        result = send_email_to_customer(user_message)
        env.log("email_sent", {"status": "success"})
    else:
        # Blocked by policy
        env.log("action_blocked", {"reason": "policy_violation"})
        result = "Action not permitted by governance policy"

With LangChain: 

from langchain.agents import AgentExecutor
from fulcrum import FulcrumClient

client = FulcrumClient(host="localhost:50051")

def governed_agent_run(agent: AgentExecutor, query: str):
    with client.envelope(workflow_id="langchain-agent") as env:
        # Pre-check the query
        if not env.guard("process_query", input_text=query):
            return {"error": "Query blocked by policy"}

        # Run agent with tool governance
        result = agent.invoke(query)
        return result

TypeScript SDK

Install: 

npm install @fulcrum-governance/sdk

Basic Integration: 

import { FulcrumClient } from '@fulcrum-governance/sdk';

// Connect to local Fulcrum
const client = new FulcrumClient({
  host: 'localhost:50051',
  apiKey: 'dev-key'  // Optional in dev mode
});

// Create governance envelope
const envelope = client.envelope({
  workflowId: 'my-support-bot'
});

// Check policy before executing
const allowed = await envelope.guard('send_email', userMessage);

if (allowed) {
  // Allowed - proceed with action
  const result = await sendEmailToCustomer(userMessage);
  envelope.log('email_sent', { status: 'success' });
} else {
  // Blocked by policy
  envelope.log('action_blocked', { reason: 'policy_violation' });
}

await envelope.complete();

With Vercel AI SDK: 

import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { FulcrumClient } from '@fulcrum-governance/sdk';

const fulcrum = new FulcrumClient({ host: 'localhost:50051' });

export async function POST(req: Request) {
  const { messages } = await req.json();
  const lastMessage = messages[messages.length - 1].content;

  const envelope = fulcrum.envelope({ workflowId: 'ai-chat' });

  // Pre-check message against policies
  if (!await envelope.guard('process_message', lastMessage)) {
    return new Response('Blocked by policy', { status: 403 });
  }

  const result = await streamText({
    model: openai('gpt-4'),
    messages,
    onFinish: async ({ usage }) => {
      envelope.log('completion', {
        inputTokens: usage.promptTokens,
        outputTokens: usage.completionTokens
      });
      await envelope.complete();
    }
  });

  return result.toAIStreamResponse();
}

View Execution Traces

After running your agent, view the execution history in the dashboard.

Using the Dashboard

  1. Navigate to Traces in the sidebar
  2. You'll see a list of recent executions (envelopes)
  3. Click any trace to inspect:
  4. Timeline: Event sequence with timestamps
  5. Policy Decisions: Which policies were evaluated
  6. Cost: Token usage and USD cost
  7. Events: Detailed action log

Using the API

# List recent traces
curl http://localhost:8080/api/v1/traces?limit=10

# Get specific trace details
curl http://localhost:8080/api/v1/traces/{trace_id}

# Get policy evaluations for a trace
curl http://localhost:8080/api/v1/traces/{trace_id}/evaluations

Trace States

Status Meaning
PENDING Envelope created, awaiting execution
RUNNING Action in progress
COMPLETED Successfully finished
BLOCKED Denied by policy
FAILED Execution error

Understanding Policy Decisions

When your agent calls env.guard(), Fulcrum evaluates all applicable policies and returns one of:

Decision Meaning Your Action
ALLOW All policies passed Proceed with action
DENY Policy violation Stop, do not execute
WARN Soft violation Proceed but log warning
REQUIRE_APPROVAL Human review needed Pause and wait

Example: Handling All Decisions

with client.envelope(workflow_id="my-agent") as env:
    decision = env.evaluate("delete_file", input_text=file_path)

    if decision.result == "ALLOW":
        delete_file(file_path)
    elif decision.result == "DENY":
        raise PermissionError(f"Blocked: {decision.message}")
    elif decision.result == "WARN":
        logger.warning(f"Policy warning: {decision.message}")
        delete_file(file_path)
    elif decision.result == "REQUIRE_APPROVAL":
        # Queue for human review
        await queue_for_approval(env.id, "delete_file", file_path)

Stopping the Stack

When you're done:

./scripts/stop-stack.sh

To remove all data and start fresh:

docker compose -f docker-compose.unified.yml down -v

Next Steps

You now have a working Fulcrum installation. Here's where to go next:

Learn More

Guide Description
Policy Authoring Advanced policy configuration
Dashboard Guide Full dashboard walkthrough
SDK Reference Detailed SDK documentation

Architecture

Document Description
System Overview High-level architecture
Cognitive Layer Semantic Judge, Oracle, Immune System

Operations

Document Description
Deployment Guide Production deployment
API Reference Full API documentation

Service Endpoints Reference

Service URL Purpose
Dashboard http://localhost:3001 Web UI
REST API http://localhost:8080 HTTP API
gRPC API localhost:50051 gRPC API
Grafana http://localhost:3000 Metrics (admin/admin)
Prometheus http://localhost:9090 Raw metrics
NATS Monitor http://localhost:8222 Event stream health

Troubleshooting

Services Not Starting

# Check logs
docker compose -f docker-compose.unified.yml logs fulcrum-server

# Verify port availability
./scripts/preflight.sh

Policy Not Triggering

  1. Verify policy is enabled in dashboard
  2. Check policy priority (higher priority = earlier evaluation)
  3. Review trace details for policy evaluation results

SDK Connection Issues

# Test connectivity
client = FulcrumClient(host="localhost:50051")
health = client.health_check()
print(f"Server status: {health.status}")

Database Reset

# Stop services
docker compose -f docker-compose.unified.yml down

# Remove volumes
docker volume rm fulcrum-postgres-data

# Restart (will re-run migrations)
./scripts/start-stack.sh

Get Help

  • Documentation: https://docs.fulcrum.dev
  • GitHub Issues: https://github.com/Fulcrum-Governance/fulcrum/issues
  • Email: support@fulcrum.dev

Document Version: 1.0 Last Updated: January 6, 2026 Target Audience: Developers new to Fulcrum