Preloop

🚀 Preloop: The Policy Engine for AI Agents

Preloop is a comprehensive MCP firewall that offers full control over the actions of AI agents. It allows you to define access policies, approval workflows, and maintain audit trails. You can allow, deny, or require approval based on specific conditions.

Preloop is also evolving into an AI workforce control plane for managed runtimes. Flows can now route model traffic through a Preloop-owned OpenAI-compatible gateway, enabling centralized enforcement of usage, spend, runtime identity, and budgets.

Works with OpenClaw, Claude Code, Cursor, Codex, and any MCP-compatible agent.

Read the official documentation: Full guides and tutorials are available at docs.preloop.ai.

🚀 Quick Start

Preloop provides a comprehensive solution for controlling AI agents. To get started, you need to understand its core capabilities and how to configure it according to your needs.

✨ Features

Why Preloop?

AI agents like Claude Code, Cursor, and OpenClaw are revolutionizing the way we work. However, they also bring significant risks:

• Accidental deletions: One wrong command can lead to the loss of your production database.
• Leaked secrets: API keys may be pushed to public repositories before anyone notices.
• Runaway costs: Agents may spin up expensive resources without limits.
• Breaking changes: Untested deployments to production at odd hours can cause disruptions.

Most teams face a difficult choice: give AI full access and move fast but dangerously, or lock everything down and sacrifice productivity. Preloop solves this problem by allowing you to define policies that enable safe operations, deny dangerous ones, and require human approval for intermediate actions. This way, you stay in control while AI handles routine tasks.

Core Capabilities

Access Policies

Define fine - grained access controls for any AI tool or operation:

• Tools support multiple ordered access rules (not just simple approval/deny).
• Rules are evaluated in priority order; the first matching rule wins.
• Each rule has an action (allow/deny/require_approval), an optional CEL condition, and an optional denial message.
• Rules can be reordered via drag - and - drop in the UI.

Approval Workflows

When an AI attempts a protected operation, Preloop pauses and notifies you:

• Instant notifications via mobile app, email, Slack, or Mattermost.
• One - tap approvals from your phone, watch, or desktop.
• Async approval mode — the tool returns immediately with a polling handle; the agent polls get_approval_status until approved, then receives the tool result (Enterprise).
• Per - tool justification — require or optionally request agents to explain why a tool is being called before approval (Enterprise).
• Team - based approvals with quorum requirements (Enterprise).
• Escalation policies for time - sensitive operations (Enterprise).

Policy - as - Code

Define policies in YAML, manage via CLI or API:

# Example: Require approval for production deployments
version: "1.0"
metadata:
  name: "Production Safeguards"
  description: "Require approval before deploying to production"
  tags: [security, production]

approval_workflows:
  - name: "deploy-approval"
    timeout_seconds: 600
    required_approvals: 1
    async_approval: true          # Agent polls instead of blocking

tools:
  - name: "bash"
    source: mcp
    approval_workflow: "deploy-approval"
    justification: required        # Agent must explain the call
    conditions:
      - expression: "args.command.contains('deploy') && args.command.contains('production')"
        action: require_approval
        description: "Production deployments require approval"

• Version control your policies alongside your code.
• GitOps workflows for policy changes.
• CLI management for automation and scripting.
• API access for programmatic policy management.

Complete Audit Trail

Every AI action is logged with full context:

• What was attempted (tool, parameters, context).
• Which policy matched and why.
• Who approved or rejected (and when).
• Execution result and duration.

This is essential for security reviews, compliance, and debugging.

AI Model Gateway

Preloop can terminate model traffic on behalf of managed runtimes instead of handing provider credentials directly to agent containers:

• OpenAI - compatible gateway endpoints: GET /openai/v1/models, POST /openai/v1/chat/completions, POST /openai/v1/responses.
• Anthropic - compatible gateway endpoint: POST /anthropic/v1/messages.
• SSE streaming support for chat completions and responses.
• Per - request attribution to account, flow, flow execution, API key, and runtime principal.
• Token and estimated - cost accounting persisted to the gateway usage ledger.
• Account - level and flow - level budget enforcement with soft - limit annotations and hard stops.
• Product - facing usage summary endpoints for account and flow monitoring.
• Account - scoped runtime session explorer endpoints for browsing managed sessions beyond flows.
• Execution - scoped gateway event inspection via GET /api/v1/flows/executions/{execution_id}/gateway-events.
• Console surfaces for browsing recent runtime sessions and searching captured gateway interactions.

Secret Custody

Preloop now stores AI model credentials behind a provider - agnostic secret abstraction:

• Built - in local_encrypted backend for simple self - hosted deployments.
• Hash - only runtime API tokens for flow executions.
• Optional external secret backend path for Vault/OpenBao - compatible KV v2 stores.
• Agent runtimes can receive short - lived Preloop gateway tokens instead of provider secrets.

Comparison with AWS Agent Core

Preloop is the open - source alternative to AWS Agent Core for teams who want vendor - neutral, self - hosted AI governance.

AI Agent -> Preloop -> [Policy check] -> Allow / Deny / Require Approval -> Execute

How it works:

1. Define policies for each tool: allow, deny, or require approval.
2. Policies can be fine - grained, checking parameter values and context.
3. AI agents call tools through Preloop's MCP proxy.
4. Actions are allowed, denied, or paused for approval based on your policies.
5. Full audit trail of every action and decision.

Key Features

Safety & Control

• Policy Engine: Define allow, deny, and approval workflows for any tool or action.
• Access Rules: Multiple ordered rules per tool with allow/deny/require approval actions.
• Drag - and - Drop Priority: Reorder rule evaluation priority visually.
• Fine - Grained Rules: Policies can check tool names, parameter values, and context.
• Instant Notifications: Get alerts on mobile, email, Slack, or Mattermost.
• One - Tap Approvals: Approve or reject from your phone, watch, or desktop.
• Full Audit Trail: Complete log of every AI action and policy decision.
• Async Approval Mode: Non - blocking approval: tool returns immediately, agent polls get_approval_status until the human decides.
• Per - Tool Justification: Require agents to provide a reason for each tool call. Mode: required (blocks without it) or optional (agent may provide one).
• Flexible Conditions: Use CEL expressions for context - aware rules (Enterprise).
• AI Approval (Enterprise): AI - driven approval with configurable model, prompt, confidence threshold, and fallback behavior.
• Team Approvals: Require quorum from multiple team members for critical ops (Enterprise).

Integration & Compatibility

• MCP Proxy: Works with any Model Context Protocol - compatible AI agent.
• Zero Infrastructure Changes: Drop - in solution, no code modifications needed.
• Built - in Tools: 11 tools for issue and PR/MR management included.
• External MCP Servers: Proxy any external MCP server through Preloop's safety layer.
• Issue Tracker Sync: Connect Jira, GitHub, GitLab for full context.

Automation Platform

• Agentic Flows: Build event - driven workflows triggered by webhooks, schedules, or tracker events.
• Gateway - Routed Model Access: Managed flows can use a Preloop - owned model gateway for centralized cost controls, telemetry, and key custody.
• Vector Search: Intelligent similarity search using embeddings.
• Duplicate Detection: Automatically identify overlapping issues.
• Compliance Metrics: Evaluate and improve issue quality.
• Web UI: Modern interface built with Lit, Vite, and Shoelace.

Looking for Enterprise features? Preloop Enterprise Edition adds RBAC, team - based approvals, advanced audit logging, and more. See Enterprise Features below.

Open Source vs Enterprise (important)

• Open Source: single - user approvals with email, mobile app, Slack, and Mattermost notifications.
• Enterprise: adds advanced conditions (CEL), team - based approvals (quorum), and escalation.
• Mobile & Watch apps: the iOS/Watch and Android apps can be used with self - hosted / open - source Preloop deployments.

📦 Installation

Prerequisites

• Python 3.11+
• PostgreSQL 14+
• PGVector extension for PostgreSQL (for vector search capabilities)

Local Setup

# Clone the repository
git clone https://github.com/preloop/preloop.git
cd preloop

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Set up the database

# Configure your environment
cp .env.example .env
# Edit .env with your settings

Docker Setup

# Clone the repository
git clone https://github.com/preloop/preloop.git
cd preloop

# Run the full development stack (backend + workers + frontend with HMR)
docker compose up

# Run with tagged release images (production)
PRELOOP_VERSION=0.8.0 SECRET_KEY=$(openssl rand -hex 32) \
  docker compose -f docker-compose.release.yaml up -d

Quick installers are also available:

# Install the standalone CLI
curl -fsSL https://preloop.ai/install/cli | sh

# Install the OSS stack
curl -fsSL https://preloop.ai/install/oss | sh

Set PRELOOP_VERSION=0.8.0 before either command to pin a specific release, or use https://preloop.ai/install/<script>?version=0.8.0.

The default docker compose up command uses docker-compose.override.yml for local development, so source changes in backend/ and frontend/ are mounted directly into the containers. The frontend runs via Vite on http://localhost:5173, while the backend API stays on http://localhost:8000.

See for full configuration and required environment variables.

Release Management

Use the release script to prepare a new version across the main release surfaces:

./scripts/release.sh 0.8.0

The script can also optionally commit the release prep, create and push v<version>, and watch the GitHub Release workflow with gh.

See for the full checklist and for the release prep helper.

Kubernetes Setup

Preloop can be deployed to Kubernetes using the provided Helm chart:

# Add the Spacecode Helm repository (if available)
# helm repo add spacecode https://charts.spacecode.ai
# helm repo update

# Install from the local chart
helm install preloop ./helm/preloop

# Or install the packaged chart from a GitHub release
# helm install preloop https://github.com/preloop/preloop/releases/download/v0.8.0-beta.3/preloop-0.8.0-beta.3.tgz

# Or install with custom values
helm install preloop ./helm/preloop --values custom-values.yaml

For more details about the Helm chart, see the chart README.

💻 Usage Examples

Starting the Server

1. Set Environment Variables: Ensure you have a .env file configured with the necessary environment variables (see .env.example). Key variables include database connection details, API keys, etc.

2. Start Preloop API: Use the provided script to start the main API server:

   ./start.sh
   

   This script typically handles activating the virtual environment and running the server (e.g., python -m preloop.server).

3. Start Preloop Sync Service: In a separate terminal, start the synchronization service to begin indexing data from your configured trackers:

   # Activate the virtual environment if not already active
   # source .venv/bin/activate
   preloop-sync scan all
   

   This command tells Preloop Sync to scan all configured trackers and update the database.

API Documentation

When running, the API documentation is available at:

http://localhost:8000/docs

The OpenAPI specification is also available at:

http://localhost:8000/openapi.json

Using the REST API

import requests
import json

# Base URL for the Preloop API
base_url = "http://localhost:8000/api/v1"

# Authenticate and get a token
auth_response = requests.post(
    f"{base_url}/auth/token",
    json={"username": "your-username", "password": "your-password"}
)
token = auth_response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# Test a tracker connection
connection = requests.post(
    f"{base_url}/projects/test-connection",
    headers=headers,
    json={
        "organization": "spacecode",
        "project": "astrobot"
    }
)
print(json.dumps(connection.json(), indent=2))

# Search for issues related to authentication
results = requests.get(
    f"{base_url}/issues/search",
    headers=headers,
    params={
        "organization": "spacecode",
        "project": "astrobot",
        "query": "authentication problems",
        "limit": 5
    }
)
print(json.dumps(results.json(), indent=2))

# Create a new issue
issue = requests.post(
    f"{base_url}/issues",
    headers=headers,
    json={
        "organization": "spacecode",
        "project": "astrobot",
        "title": "Improve login error messages",
        "description": "Current error messages are not clear enough...",
        "labels": ["enhancement", "authentication"],
        "priority": "High"
    }
)
print(json.dumps(issue.json(), indent=2))

📚 Documentation

API Endpoints

Preloop provides a comprehensive REST API for authentication, tool management, approval workflows, policy generation, and integrations.

For the complete REST API reference, including interactive Swagger endpoints, please see the official API documentation.

Unified WebSocket

Preloop uses a unified WebSocket connection for real - time updates across the application:

Connection: ws://localhost:8000/api/v1/ws/unified

Message Routing:

• Flow execution updates (flow_executions topic)
• Approval request notifications (approvals topic)
• System activity updates (activity topic)
• Session events (system topic)

Features:

• Automatic reconnection with exponential backoff
• Pub/sub message routing to subscribers
• Topic - based filtering for efficient message delivery
• Session management with activity tracking
• Heartbeat monitoring

Usage in Frontend:

import { unifiedWebSocketManager } from './services/unified-websocket-manager';

// Subscribe to flow execution updates
const unsubscribe = unifiedWebSocketManager.subscribe(
  'flow_executions',
  (message) => console.log('Flow update:', message),
  (message) => message.execution_id === myExecutionId  // Optional filter
);

// Clean up when done
unsubscribe();

Using MCP Tools via API

The Preloop API includes integrated MCP tool endpoints with dynamic tool filtering, allowing any HTTP - based MCP client to connect directly.

Read the MCP Integration Guide in docs.preloop.ai for details on authenticating clients like Claude Code, Cursor, and Windsurf, and setting up workflows or timeouts.

Mobile Push Notifications (iOS/Android)

Open - source users can enable mobile push notifications by proxying requests through the production Preloop server at https://preloop.ai.

Setup Steps:

1. Create an account at https://preloop.ai
2. Generate an API key with push_proxy scope from the Settings page
3. Configure your instance with these environment variables:

# Push notification proxy configuration
PUSH_PROXY_URL=https://preloop.ai/api/v1/push/proxy
PUSH_PROXY_API_KEY=your-api-key-here

4. Enable push notifications in the Notification Preferences page in your Preloop Console
5. Register your mobile device by scanning the QR code shown in Notification Preferences

Once configured, approval requests will trigger push notifications on your registered iOS or Android devices.

Note: The mobile apps (iOS/Watch and Android) are designed to work with self - hosted Preloop instances. They connect to your server URL extracted from the QR code.

Version Checking & Updates

By default, Preloop checks for version updates by contacting https://preloop.ai on startup and once daily. This helps you stay informed about new releases and security updates.

Privacy: Only instance UUID, version number, and IP address are sent. No user data is transmitted.

Opt - out: Set PRELOOP_DISABLE_TELEMETRY=true or DISABLE_VERSION_CHECK=true to disable version checking and telemetry entirely.

For detailed architecture, see ARCHITECTURE.md.

🔧 Technical Details

Testing

Preloop uses pytest for unit and integration testing. The test suite covers API endpoints, database models, and tracker integrations.

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/endpoints/test_webhooks.py

# Run a specific test case
pytest tests/endpoints/test_webhooks.py::TestWebhooksEndpoint::test_github_webhook_valid_signature

Test Structure

• Unit Tests: Located in tests/ directory, testing individual components in isolation.
• Integration Tests: Test the interaction between components.
• Endpoint Tests: Test API endpoints with mocked database sessions.

Testing Webhooks

The webhook endpoint tests (tests/endpoints/test_webhooks.py) validate:

1. Authentication via signatures/tokens for GitHub and GitLab webhooks.
2. Error handling for invalid signatures, missing tokens, etc.
3. Organization identifier resolution.
4. Database updates (last_webhook_update timestamp).
5. Error handling for database failures.

These tests use mocking to isolate the webhook handling logic from external dependencies.

Roadmap

Preloop is evolving into a comprehensive control plane for AI agents. Here's what's coming:

• 🔜 Agent Registry — Register, credential, and manage AI agents as first - class entities.
• 🔜 AI Model Gateway — Unified model proxy with cost tracking, rate limits, and usage analytics.
• 🔜 Agent Monitoring — Real - time visibility into agent activity, spending, and health.
• 🔜 Budget Controls — Per - agent spending caps with alerts and enforcement.

Star the repo and watch for updates!

Enterprise Features

Preloop Enterprise Edition extends the open - source core with additional features for teams and organizations:

Contact sales@preloop.ai for Enterprise Edition licensing.

📄 License

Preloop is open source software licensed under the Apache License 2.0.

Copyright (c) 2026 Spacecode AI Inc.