PolicatePolicate

Policate documentation · product, binary, API

Run AI with control, not guesswork.

A practical guide to routing, budgets, operating modes, the local binary, managed tools, and cost allocation. Each section includes a real command or payload you can try in a workspace.

macOS · Linux · Windows · one signed installer · one-month trial

Start one-month trial See the control plane

01 · Routing

Make every model decision explainable.

Policate evaluates the request before it reaches a provider. The active policy filters models, then the router scores capability, cost, latency, reliability, and team preference. The decision is recorded as a receipt you can inspect in the dashboard or from the binary.

  • Policy versions are activated by an owner and cached at the gateway for fast, deterministic decisions.
  • Fallbacks are explicit: a provider outage or budget boundary never silently changes the allowed model set.
  • Every response includes the selected model, policy version, estimated cost, and a trace identifier for audit.
A route receiptexample
{\n  "intent": "refactor-auth-handler",\n  "selected": "claude-sonnet-4-6-bedrock",\n  "reason": ["capability", "within_budget", "healthy"],\n  "fallback": "gpt-4.1-mini",\n  "policyVersion": 14,\n  "estimatedUsd": 0.018\n}
$ policate models && policate policy test --input "refactor this auth handler"

02 · Operating modes

Gateway first. Direct when the boundary requires it.

Gateway mode is the recommended default: budgets, redaction, policy, routing, caching, and audit stay authoritative at the control plane. Direct mode is an explicit organization opt-in for teams that must keep provider traffic inside their own network.

  • Gateway mode gives the strongest central enforcement and the richest usage, savings, and audit telemetry.
  • Direct mode never receives provider secrets from Policate. The binary applies the signed, secret-free company bundle locally.
  • The dashboard labels the active mode and warns when a direct request cannot be centrally observed.
Choose the boundaryexample
$ policate mode gateway\nactive mode: gateway · policy, budgets, audit enforced\n\n$ policate mode direct\nactive mode: direct · local policy bundle v14\nprovider traffic stays in your environment
$ policate config status

03 · Binary

One familiar workflow on every developer machine.

The Policate binary wraps the Oh My Pi workflow and adds managed configuration, model routing, receipts, and cost-aware defaults. Install on macOS, Linux, or Windows, then authenticate once. On startup it fetches the approved company bundle and applies managed tools and instructions without overwriting personal files.

  • Startup sync is idempotent and produces a receipt, so a laptop can be checked without reading raw provider credentials.
  • Use the same interactive TUI, slash commands, shell escapes, and streaming responses as the underlying local workflow.
  • The company can enforce presets, skills, hooks, context limits, and update policy while developers keep personal settings.
From install to healthy syncexample
$ curl -sSL https://policate.marcllort.com/install/cli | sh\ninstalled policate v0.1.7\n$ policate login\nauthenticated · acme-corp · developer\n$ policate doctor\nok gateway · policy v14 · models 3\nok managed tools 4 · skills 12 · hooks 2\nok startup sync · receipt sealed
$ policate doctor --json

04 · Controls

Set the guardrails once, keep them everywhere.

Company owners define the context window ceiling and automatic compaction threshold alongside budgets, hard limits, redaction, residency, and model allowlists. The dashboard is the source of truth; the binary displays the effective values before a request starts.

  • Context and autocompact values are organization-level defaults with optional team overrides.
  • Budget checks happen before provider invocation and return a useful explanation when a request is blocked.
  • Redaction removes secrets and sensitive identifiers before telemetry or cache writes; raw prompts are never used as tags.
Effective company policyexample
{\n  "context": { "maxTokens": 120000, "autocompactAt": 96000 },\n  "budget": { "monthlyUsd": 2000, "hardStop": true },\n  "models": { "allow": ["claude-sonnet-4-6-bedrock", "gpt-4.1-mini"] },\n  "redaction": "strict",\n  "residency": "us"\n}
$ policate config status && policate budget status

05 · Workspace

Curate the tools agents can actually use.

Approve MCP servers, skills, commands, subagents, and pre-commit hooks from the dashboard. Teams get a safe baseline while developers retain their personal configuration. Managed changes are signed, scoped, and applied on the next startup sync.

  • MCP entries are allowlisted by server, command, and permission scope instead of being copied blindly into every machine.
  • Hooks can review staged changes, flag secrets, or require a policy check before a commit is created.
  • The dashboard shows which machines acknowledged a bundle and which are still on an older version.
A managed workspace bundleexample
workspace:\n  tools:\n    - name: linear\n      scope: read\n    - name: github\n      scope: pull_requests\n  hooks:\n    - review: staged\n    - secret_scan: strict\n  skills: ["incident-review", "cost-aware-routing"]
$ policate tools status && policate hooks review --staged

06 · Allocation

Turn token usage into an operating signal.

Tag sessions manually or attribute sanitized GitHub and Jira references to a project. Usage rolls up by project, work item, session, model, and provider so finance and engineering can see where spend went and which model combinations deliver the best value.

  • Tags are explicit metadata; detected issue references are normalized and never include full ticket or prompt contents.
  • The dashboard compares routed spend with an ungoverned baseline and shows savings by model, project, and time window.
  • Export usage for finance, or let the Policate MCP answer questions such as “what did the migration project spend this week?”
Name a session without leaking contentexample
$ policate session tag --project billing-migration --jira PLAT-1842\nsession tagged · billing-migration · PLAT-1842\n\n$ policate usage --project billing-migration --since 7d\nrequests 842 · tokens 18.4M · routed spend $126.40 · saved 41%
$ policate usage --group-by project,model --since 30d

07 · AI-native control

Operate Policate from any MCP client.

Create a dashboard API token with admin:read and, when needed, admin:write. Add the server below to Claude Desktop, Cursor, an internal agent, or any compatible MCP client. Provider credentials never leave the control plane.

{
  "mcpServers": {
    "policate": {
      "url": "https://policate.marcllort.com/api/mcp",
      "headers": { "Authorization": "Bearer <POLICATE_API_KEY>" }
    }
  }
}

The server exposes organization, context policy, active policy, managed tools, usage, tokens, operating mode, and policy activation with scope and role checks. Raw tokens and provider secrets are never returned.

Quick start

From install to your first governed request.

$ curl -sSL https://policate.marcllort.com/install/cli | sh\n$ policate login\n$ policate mode gateway\n$ policate doctor\nok · ready to route your first request

A new workspace starts with a safe trial for up to 10 users. Choose Gateway or Direct mode, connect a provider, select a regional preset, activate the policy, then create a token. For product questions, use the Help Center.