Praetor

This page is synchronized from the canonical English documentation. 日本語 navigation is available; commands and product limits are identical in every locale.

Approval and Recovery Plane for Coding & DevOps AI Agents

Exact request approval · Query uncertain outcomes · Verify signed evidence

Alpha. Making agents worthy of enterprise trust is our long-term mission. The first pilot is limited to GitHub pull-request creation; no universal exactly-once or production-readiness guarantee is implied.

Mission. Mechanisms. Evidence.

Explore all three films →

The mission 0:29

Make agents worthy of enterprise trust.

Can enterprises trust agents with important work? This is the long-term problem we are working to solve.

Brand vision · Alpha; a mission still being built

▶ 1:58

The engineering 1:58

The engineering of trust.

Exact request authority, stale-worker fencing, uncertain outcomes, and signature checks that reject altered evidence.

Mechanism illustrations · Component tests, including in-memory repositories and mocked HTTP

▶ 0:38

The live API experiment 0:38

The reply is lost. The PR is found.

Real GitHub API, Gateway and PostgreSQL: inject a lost reply, restart the worker, and recover the existing pull request.

Animated reconstruction of a CI run · Injected faults, no LLM, not a production incident

English on-screen text with an instrumental score, no voiceover. English captions and text transcripts are available.

Autonomous agents are rapidly taking on mission-critical workflows: modifying codebases, opening pull requests, running database migrations, and provisioning cloud infrastructure. But when an agent makes an external write, a network timeout, dropped socket, or worker restart leaves the system in an ambiguous state: did the write happen, how many times, and with what payload?

Blindly retrying creates duplicate PRs, double transactions, and corrupted state. Simply giving up leaves orphaned mutations.

Praetor builds execution controls around this problem. It records approved requests and execution state outside the agent, uses adapter-specific outcome queries to determine whether a write took effect, and preserves UNKNOWN when the evidence is ambiguous. Recovery depends on the adapter, remote query semantics, and deployment configuration.

View Text Architecture Diagram (ASCII)

   ┌────────────────────────────────────────────────────────┐
   │        AI Agent Frameworks & LLMs                      │
   │  Claude Code · Cursor · OpenAI Agents · LangGraph      │
   └──────────────────────────┬─────────────────────────────┘
                              │ 1. Propose Mutation (No direct write tokens)
                              ▼
   ┌────────────────────────────────────────────────────────┐
   │            Praetor Control Plane                     │
   │  ┌─────────────────────────┐ ┌──────────────────────┐  │
   │  │ Preflight Idempotency   │ │ Two-Phase Human Gate │  │
   │  │ (Query-Before-Retry)    │ │ (Cryptographic Hash) │  │
   │  └─────────────────────────┘ └──────────────────────┘  │
   │  ┌─────────────────────────┐ ┌──────────────────────┐  │
   │  │ Durable Postgres Kernel │ │ Tamper-Evident Audit │  │
   │  │ (Crash-safe step lease) │ │ (Ed25519 signatures) │  │
   │  └─────────────────────────┘ └──────────────────────┘  │
   └──────────────────────────┬─────────────────────────────┘
                              │ 2. Governed Write & Authorized Compensation
                              ▼
   ┌────────────────────────────────────────────────────────┐
   │       External Infrastructure & Version Control        │
   │   GitHub (PRs/Issues) · Kubernetes · Cloud APIs        │
   └────────────────────────────────────────────────────────┘

Read the technical essay: Why retrying an AI agent's external action is unsafe.

The Distributed Systems Problem for AI Agents

Challenge	Naive Agent Execution	Praetor Governed Action
Response Loss (e.g. 504 Gateway Timeout during PR creation)	Re-plans or retries blindly → Duplicate PRs & mutations	Preflight Query-Before-Retry: Checks remote outcome by action identity before retry
Worker Crash Mid-Task	State lost or restarted from zero with orphaned external side effects	Durable PostgreSQL Kernel: Step lease reclaims; effect-bearing work waits for reconciliation
Credential Exposure	Agent process directly holds write API keys / GitHub tokens	Strict Boundary: In the configured pilot, agents propose; adapter credentials stay worker-side
Human Sign-Off	Text-based prompt or unverified button	Cryptographic Binding: Approval locks immutable request digest & policy snapshot
Audit & Forensics	Ephemeral console text	Ed25519 Evidence: Signed evidence verifiable with the trusted public key
Rollback / Undo	Ad-hoc scripts or impossible	Governed Compensation: Requires separate authorization binding and dedicated receipt

⚡ 4 Ways to Experience Praetor (Under 60 Seconds)

Path	Command	What It Exercises
1. Zero-Dependency Demo	pnpm demo:l4-a	Multi-agent deliberation, 5 quality gates, in-memory execution (no API key needed)
2. Real Provider Code Review	pnpm exec tsx packages/core/src/cliEntry.ts review --commit HEAD --real --provider=openai	Read-only analysis of your Git diff across configured quality gates
3. Interactive Web Console	pnpm gui	Live control room on :5173: agent topology, DLQ inspection, and approval queue
4. Governed Action Offline Test	pnpm test:github:offline	130 offline contract assertions for idempotency & response-loss recovery

📦 SDK & MCP Integration

Python SDK (praetor-ai)

from commander import CommanderClient

async with CommanderClient(base_url="http://127.0.0.1:4000", api_key="cmd-...") as client:
    # Deliberation planning without LLM costs
    plan = await client.plan("Audit repository for security vulnerabilities")
    print(f"Topology: {plan.topology} ({plan.estimated_steps} steps, est: ${plan.estimate.cost_budget_usd:.2f})")

    # Run execution with configured quality gates
    result = await client.run("List and verify all public exported interfaces")
    print(f"Status: {result.status} — {result.summary}")

Governed Action Gateway (Python)

from commander import CommanderGatewayClient, ProposeActionInput

async with CommanderGatewayClient(base_url="http://127.0.0.1:4000", api_key="cmd-...") as gateway:
    # Propose external mutation with preflight idempotency
    action, replay, accepted = await gateway.propose_action(
        ProposeActionInput(
            source="coding-agent",
            destination="github://octo-org/repo",
            effect_type="github.pullRequestCreate",
            args={"title": "fix: prevent token replay", "head": "fix-auth", "base": "main"},
            idempotency_key="0191ec4d-91b4-7b98-b80c-7b897914e1a0",
        )
    )
    print(f"Action {action.run_id}: state={action.state}, approval={action.decision.effect}")

Universal Model Context Protocol (MCP)

Works with Claude Code, Cursor, Windsurf, LangGraph, or OpenAI Agents SDK:

{
  "mcpServers": {
    "commander": {
      "command": "commander-mcp-server",
      "env": {
        "PRAETOR_ACTION_GATEWAY_URL": "http://127.0.0.1:4000",
        "PRAETOR_API_KEY": "cmd-..."
      }
    }
  }
}

Core Architecture & Capabilities

Praetor provides a robust execution fabric that separates agent reasoning from external side-effects:

• Deliberation Engine: Classifies incoming tasks by complexity and automatically selects one of five canonical execution topologies (SINGLE, CHAIN, DISPATCH, ORCHESTRATOR, REVIEW).
• 25 LLM Providers with Auto-Failover: Seamlessly fallback across OpenAI, Anthropic, Gemini, Groq, Mistral, Ollama, DeepSeek, and 18 others with unified configuration. See Providers.
• 18 Built-in Tools & Native MCP: Built-in shell, filesystem, and Git tools with capability trust tiers, plus full Model Context Protocol (stdio MCP) server support. See Tools and MCP.
• Multi-Layer Quality Verification: Configurable evaluation pipeline assessing hallucination, consistency, completeness, accuracy, and safety before mutations take effect.
• Distributed Durability: Circuit breakers, dead-letter queues (DLQ), saga compensation, and PostgreSQL-backed crash-safe step leasing.
• Governed Mutation Plane: Capability tokens, policy decisions, cryptographic human approval binding, and Ed25519-signed evidence receipts.

Enterprise evaluation & pilots

Praetor is alpha. Two evaluation paths are available:

• GitHub Pilot (governed actions & recovery): A narrow pilot for same-repository PR creation from existing branches. An agent proposes the action; a human approves the exact request. When network responses drop, recovery queries GitHub using persisted action identity rather than creating duplicate PRs. See the GitHub pilot guide.
• Shadow Phase A (historical evaluation): Customer-operated evaluation of historical observations against a pinned policy. It executes no external actions. Download the Shadow Phase A release package.
• Enterprise Pilot Readiness: An explicit checklist of security, multi-tenancy, SLO, and data governance controls with code and baseline evidence pointers. Review ENTERPRISE_READINESS.md before production pilots.

Development product paths

• Local CLI: the supported default for one developer or a local team.
• Web console: a local interface served with the API.
• Enterprise Gateway: an alpha /v1 server path (apps/api → @praetor/kernel Postgres → worker-plane + effect-broker). It is not a production-proven multi-tenant SaaS.

Start here

Page	What it covers
Quick start	Install, run the simulated demo, start the interfaces
CLI reference	Every command, subcommand, and flag
HTTP API	Endpoints, authentication, and the /v1 Gateway
Configuration	Environment variables and storage backends
Tools	The 18 built-in tools, trust tiers, and MCP filtering
Providers	All 25 providers, env variables, failover, model tiers
MCP	The stdio MCP server, both modes, and the command allowlist
Web console	Console routes and how to start it
Architecture	Topologies, quality gates, and the V2 plane
Workflows and automation	Workflows, scheduler, webhooks, background jobs
Packages and SDKs	Workspace packages, TypeScript/Python SDKs, plugins
SDK and API overview	SDKs, OpenAPI documents, and client usage
Deployment	Supported local installation and profiles
Operations and rollback	Health checks, recovery, and rollback limits
Security and privacy	Authentication, sandboxing, governed writes, caveats
Troubleshooting	Common failures and how to fix them
Benchmarks	What the benchmarks do and do not prove
Support and limits	Current product boundary

Read Security and privacy before connecting customer data or third-party tools.

What this site promises

This site documents supported commands, configuration boundaries, and known limits. It does not treat simulated benchmarks, CI fixtures, or compliance reporting scaffolds as production evidence or certification.