> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/architecture/policies.md).

# Policies

Tenant policy selects which systems and operations an agent may request, when approval is required, and where held actions route. Policy evaluation is side-effect free.

```json
{
  "allowed_systems": ["kubernetes"],
  "allowed_operations": {
    "kubernetes": ["restart_service", "scale_deployment"]
  },
  "parameter_constraints": {
    "kubernetes": {
      "scale_deployment": {
        "deployment": {"equals": "checkout"},
        "replicas": {"min": 2, "max": 5}
      }
    }
  },
  "approval_required_at": "medium",
  "review_route": "ops-approvers"
}
```

### Fields

| Field                   | Meaning                                                                          |
| ----------------------- | -------------------------------------------------------------------------------- |
| `allowed_systems`       | Registered actuator names this tenant may target.                                |
| `allowed_operations`    | Per-system operation allowlist. Strict production use requires explicit entries. |
| `parameter_constraints` | Optional bounds evaluated against `action.parameters`.                           |
| `approval_required_at`  | Minimum effective risk that holds: `low`, `medium`, or `high`.                   |
| `review_route`          | Human or service route returned with `needs_approval`.                           |

Parameter paths are relative to `action.parameters`. Use dot paths for nested objects.

| Constraint | Meaning                                               |
| ---------- | ----------------------------------------------------- |
| `required` | Whether the parameter must exist. Defaults to `true`. |
| `equals`   | Exact required value.                                 |
| `one_of`   | Allowed values.                                       |
| `min`      | Numeric lower bound.                                  |
| `max`      | Numeric upper bound.                                  |

### Decision rules

| Result           | When                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `allow`          | Proposal and trusted parameters are valid, the operation is allowed, and effective risk is below the approval threshold. |
| `needs_approval` | The operation is allowed, but effective risk is at or above the threshold.                                               |
| `deny`           | The system, operation, or parameter is outside policy, or trusted semantics cannot be established.                       |

Actuators run only after `allow` or an authenticated approval.

### Policy versus catalog

Policy answers **may this tenant request the operation?** The operation catalog answers **what does that operation mean?**

| Policy                          | Reviewed operation catalog         |
| ------------------------------- | ---------------------------------- |
| System and operation allowlists | Closed parameter schema            |
| Approval threshold and route    | Minimum risk and effects           |
| Optional parameter bounds       | Reversibility and actuator binding |
| Tenant-specific authorization   | MCP tool-schema commitment         |

Continue with Operation catalogs and admission.

### Templates

```sh
curl -sS "$WARRANT_URL/v1/policy-templates"
```

Each starter includes `mock_actuators`, policy JSON, and an example proposal. Treat it as a safe starting point, then review it for your own systems.

### Validate and update

Validate without mutating a tenant:

```sh
curl -sS "$WARRANT_URL/v1/policies/validate" \
  -X POST \
  -H "X-Warrant-Admin-Key: $WARRANT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_systems": ["kubernetes"],
    "allowed_operations": {"kubernetes": ["restart_service"]},
    "approval_required_at": "medium",
    "review_route": "ops-approvers"
  }'
```

Apply a reviewed revision:

```sh
curl -sS "$WARRANT_URL/v1/tenants/acme-agents/policy" \
  -X PUT \
  -H "X-Warrant-Admin-Key: $WARRANT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "change_note": "tighten restart policy",
    "policy": {
      "allowed_systems": ["kubernetes"],
      "allowed_operations": {"kubernetes": ["restart_service"]},
      "approval_required_at": "low",
      "review_route": "ops-approvers"
    }
  }'
```

Updates apply to future proposals. Each change creates an immutable revision with the normalized policy, policy/catalog hashes, authenticated author, time, and change note.

```sh
curl -sS "$WARRANT_URL/v1/tenants/acme-agents/policy/revisions" \
  -H "X-Warrant-Admin-Key: $WARRANT_ADMIN_KEY"
```

### Dry-run a proposal

`policy/check` returns a verdict without creating an action, approval, execution job, or audit event:

```sh
curl -sS "$WARRANT_URL/v1/tenants/acme-agents/policy/check" \
  -X POST \
  -H "X-Warrant-Admin-Key: $WARRANT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proposal": {
      "proposal_id": "policy-check-restart",
      "actor": {"agent_id": "agent-1"},
      "summary": "Restart checkout in staging",
      "action": {
        "target_system": "kubernetes",
        "operation": "restart_service",
        "parameters": {"service": "checkout", "environment": "staging"},
        "rollback_plan": "restart the previous revision"
      },
      "risk": {"level": "medium", "blast_radius": "checkout staging traffic"}
    }
  }'
```

Omit `policy` to use the current policy. Include it beside `proposal` to evaluate a draft.

### Trusted operation catalogs

Catalog authoring, enforcement modes, schema pins, and strict admission are documented on Operation catalogs and admission.

### Policy regression fixtures

CI fixtures and bounded reachability checks are documented on Policy regression and verification.

### Verify reachability

See Policy regression and verification for counterexamples, typed world models, and verification limits.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/architecture/policies.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.