Policate docs · 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 · checksum-verified downloads · 14-day trial

Start 14-day trial See the control plane

01 · Routing

Make every model decision explainable.

In Gateway mode, Policate evaluates the request before it reaches a provider: policy filters the candidate set, then the router scores capability, cost, latency, reliability, and team preference. Direct mode receives approved role selectors and fallback chains in the local bundle; those selectors apply after a task is delegated rather than silently rerouting the initial parent prompt.

Policy filters first

Region, provider, model allowlists, capability, and hard organization rules determine which candidates are eligible before any score is compared.

Routing ranks what remains

Cost, latency, reliability, and task fit rank the eligible candidates. A fallback is a named policy outcome, not a hidden provider substitution.

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.
Gateway responses include the selected model, policy version, estimated cost, and a trace identifier for audit. Direct keeps local role and fallback evidence without claiming authoritative server traces.

A route receiptexample

{
  "intent": "refactor-auth-handler",
  "selected": "claude-sonnet-4-6-bedrock",
  "reason": ["capability", "within_budget", "healthy"],
  "fallback": "gpt-4.1-mini",
  "policyVersion": 14,
  "estimatedUsd": 0.018
}

$ policate models && policate policy test --input "refactor this auth handler"

02 · Operating modes

Gateway first. Direct when the signed runtime is ready.

Gateway mode is the safe starting path: every request can remain centrally enforceable. Direct is an explicit provider-direct choice after the binary and Admin have a verified, content-hashed runtime contract.

Start with Gateway

Use Gateway for the first governed request and whenever a budget, redaction rule, cache decision, or audit record must be enforced and observed centrally.

Choose Direct when ready

Use Direct after the deployment has both the Admin signing key and the client verifier configuration, when provider ownership or network boundaries matter most.

Direct keeps the same dashboard, managed startup sync, approved models, tools, context controls, role selectors, and fallback data.
Gateway keeps hard central budgets, response redaction, exact cache, provider credential isolation, server-side routing, and complete request evidence authoritative.
The dashboard labels the active mode and warns when a Direct request cannot be centrally observed. Existing organizations keep their saved choice.

Choose the boundaryexample

$ policate mode direct
active mode: direct · local bundle v14
provider traffic stays in your environment

$ policate mode gateway
active mode: gateway · central policy, budgets, redaction, cache, audit

$ 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, delegated model roles and fallbacks, receipts, cost-aware defaults, and bounded agent execution profiles. 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 is the synchronization boundary

The binary authenticates, compares the managed manifest, applies the company namespace atomically, and then launches the interactive runtime.

Personal configuration remains personal

Policate-owned blocks are versioned separately. User-authored files outside those blocks are preserved unless an organization setting explicitly supersedes the effective value.

Spend frontier intelligence where it matters

Adaptive orchestration keeps architecture with the planner, routes bounded leaves to approved worker roles, and adds independent review only when risk or fan-in warrants the extra model call.

Persistent work stays easy to find

The global Agents view groups working, input-ready, and completed conversations without requiring you to reopen the repository where each session started.

Startup sync is idempotent and produces a receipt, so a laptop can be checked without reading raw provider credentials.
Adaptive already delegates up to four economical workers when decomposition pays off. High Assurance reserves the strongest approved model for planning and final review. There is no separate swarm mode.
Open `policate agents` from any directory to see authorized top-level conversations across local projects. Open a conversation, then press Left Arrow on an empty prompt to return to the list without stopping it. Git work gets a private checkout; non-Git work runs in its selected folder.
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
installed policate v0.1.22
$ policate login
authenticated · acme-corp · developer
$ policate doctor
ok provider path · policy v14 · models 3
ok managed tools 4 · skills 12 · hooks 2
ok startup sync · manifest hash verified

$ policate optimize adaptive && policate agents

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 controls shared through Gateway and Direct runtime configuration.
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

{
  "context": { "maxTokens": 120000, "autocompactAt": 96000 },
  "budget": { "monthlyUsd": 2000, "hardStop": true },
  "models": { "allow": ["claude-sonnet-4-6-bedrock", "gpt-4.1-mini"] },
  "redaction": "strict",
  "residency": "us"
}

$ 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 versioned, 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.
The Knowledge surface currently stores source metadata plus connector metadata and encrypted connection profiles. Its retrieval runtime is not enabled, so connectors are not called and saved sources are not injected into model requests.

A managed workspace bundleexample

workspace:
  tools:
    - name: linear
      scope: read
    - name: github
      scope: pull_requests
  hooks:
    - review: staged
    - secret_scan: strict
  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 use local metadata detection to infer sanitized GitHub and Jira references for a project. The managed default asks for an allocation before work starts and confirms it only once per hour. Usage rolls up by project, work item, session, model, and provider so finance and engineering can see where spend went.

Allocation hierarchy

Organization totals roll into team, project, work item, session, user, model, and provider views without using prompt text as a label.

Evidence differs by mode

Gateway supplies authoritative request receipts. Direct can preserve local tags and receipts, but central request allocation is incomplete unless compatible usage metadata is explicitly reported.

Reference inference reads bounded repository, branch, and work-item text locally. It accepts Jira IDs or safe Jira Cloud links and GitHub issue or pull-request references. This is not an authenticated GitHub or Jira integration and it does not resolve or modify remote issues.
Workspace admins choose GitHub/Jira sources, hour/turn/off reminder cadence, required allocation, and whether Scratch is available. Scratch stays usable for ad-hoc work but is explicitly marked as less useful for delivery reporting.
Tags are metadata only; detected references never include ticket bodies, prompts, model responses, source code, or tool content.

Name a session without leaking contentexample

$ policate session tag --project billing-migration --work-item PLAT-1842
Session labels saved. They will be attached to new requests.

> /work https://company.atlassian.net/browse/PLAT-1842
work: PLAT-1842

> /work scratch
Now tracking Scratch (not attributed to delivery work).

$ policate status --json

07 · Spend intelligence

Give managers an explanation, not just an invoice.

The Cost & usage view is designed for platform and finance teams. It combines request metadata into cost per request, cost per million tokens, routing shifts, cache reuse, attribution coverage, and member-level spend. Smart signals call out concentration, fallback spikes, low cache reuse, latency tails, and unallocated projects so a manager knows what to investigate next.

Core cost metrics

Requests, input/output/cache tokens, actual and estimated cost, cost per request, cost per million tokens, baseline cost, and measured savings.

Operational metrics

Routing shifts, fallback rate, exact-cache reuse, latency P95, member concentration, and attribution coverage explain where to intervene.

Harness metrics

Track context compaction, bounded reads, retry loops, and successful task outcomes separately from model-routing savings so an efficient local workflow is not hidden inside one number.

Member-level rows are visible only to owners, admins, security, finance, and auditors. Developers and restricted users receive their own efficiency summary without teammate activity.
Actual provider cost is preferred when present; estimated cost is used as a transparent fallback so a partial provider receipt never makes spend disappear.
Signals are advisory and deterministic. They never change a policy or automatically message a teammate; configure an alert rule when a threshold should notify a channel.
The view stores metadata only: model, provider, token counts, latency, cache status, tags, and cost. Raw prompts are not used to build the report.

A manager usage responseexample

{
  "efficiency": {
    "costPerRequestUsd": 0.014,
    "costPerMillionTokensUsd": 8.72,
    "routingShiftRate": 0.68,
    "attributedCostRate": 0.91
  },
  "insights": [{
    "code": "low_cache_reuse",
    "severity": "warning",
    "recommendation": "Enable exact or prefix caching"
  }],
  "byUser": [{ "email": "dev@acme.com", "costUsd": 42.18 }]
}

$ Dashboard → Spend intelligence → Smart signals

08 · 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 bounded tools including policate_get_org, policate_get_integrations, policate_update_context_policy, policate_activate_policy, and policate_reset_onboarding. Every call is limited by token scope and the same role-to-view permissions as the dashboard; mutations also require an owner or admin role and are audited. It does not create or manage providers, users, budgets, or API tokens. Provider/connector secrets and raw tokens are never returned, and secret-bearing setup stays in the dashboard.

Quick start

From install to your first governed request.

$ curl -sSL https://policate.marcllort.com/install/cli | sh
$ policate login
$ policate mode direct
$ policate doctor
ok · managed bundle current · provider path ready

A new workspace starts with a 14-day trial for up to 10 users and Gateway mode preselected. Connect a provider, select a regional preset, activate the policy, then install the binary. Choose Direct later when its signed runtime setup is ready. For product questions, use the Help Center.