Policy
Orchestrate uses Open Policy Agent (OPA) to decide what is allowed. Every model call, model deploy and tool call asks OPA first, and every answer is written to the audit log.
Policy works on top of roles. A person still needs the right role on a project to act in it. Policy can then refuse what a role would allow, or require a person to approve it.
What asks for a decision
| Action | Asked by | When |
|---|---|---|
chat | Model Gateway | Every chat completion |
embed | Model Gateway | Every embeddings request |
transcribe | Model Gateway | Every speech-to-text request |
speak | Model Gateway | Every text-to-speech request |
deploy_model | API | Every model deploy |
verify_model_integrity | Deployment controller | A deploy of an image Orchestrate has no build record for (unattested) |
call_tool | Tool execution, the API | Every connector tool call, every MCP tool call from a code agent, and every call from one agent to another (connector_type agent) |
For tool calls, the agent run also asks a second question before the call: does it need a person to approve it? See Human approval.
If OPA cannot be reached or gives no clear answer, the action is refused with Denied by policy. If the approval question cannot be answered, the tool call waits for a person. An OPA outage stops model and tool calls rather than letting them through.
Where rules come from
- The baseline policy ships with Orchestrate, inside the Helm chart. It is not set from your values file. Add to it with custom policies. Contact us if you need a different baseline.
- Custom policies are rules a platform admin writes in the console or imports as a file.
- Guardrails are a separate, built-in check on model calls, for personal data and prompt injection. See PII guardrails and Guardrail profiles.
- Model access restricts models to projects, and is checked by the Model Gateway on every model call. See Model access.
A custom deny beats everything. A custom allow can only add to the baseline, and only for tool calls.
The baseline policy
| Action | Baseline rule |
|---|---|
chat, embed, transcribe, speak | Allowed. |
deploy_model | Allowed. The caller's roles are checked first. |
verify_model_integrity | Unattested images are allowed. A changed image is always refused, before policy is asked. See the integrity check. |
call_tool, reading | Allowed. |
call_tool, write tools on the list | Allowed only in the projects on the allow list. |
| Approval | Required for every call that can write, and for every tool on the write-tool list. |
Out of the box, the write-tool list is salesforce_create_record and o365_send_mail, and the allow list has one project, Default.
The Governance page
Open Governance to see the rules and their effects. You need the platform admin role.
| Section | What it shows |
|---|---|
| Blocked actions | Everything the platform refused, newest first, read from the audit log: policy denials, guardrail refusals and rejected approvals, each with its reason. |
| Pending approvals | Tool calls across every project that are waiting for a person. |
| Rules in force | What the Model Gateway does about personal data, read live from the gateway, and which tools the baseline policy treats as write tools and who may call them, read live from OPA. |
| Custom policies | The rules admins have added, and whether OPA has loaded them yet. |
| Known governance gaps | Controls the platform does not enforce yet. |
| Compliance | The AI registry, compliance packs and evidence bundles. See Compliance. |
A policy denial in the audit log looks the same whether a rule refused the call or OPA could not be reached. Blocked actions says so.
Custom policies
A custom policy has a name, an effect, an action and conditions.
Effects
| Effect | Actions | What it does |
|---|---|---|
| Deny | Any | Refuses matching requests, whatever the baseline says. |
| Require approval | call_tool | Makes matching tool calls wait for a person. |
| Allow | call_tool | Lets matching tool calls run where the baseline refuses them. Must name the projects it applies to. |
Conditions
A condition is a field and a list of values. A request matches when every condition matches. A policy with no conditions matches every request for its action.
| Action | Fields you can test |
|---|---|
call_tool | tool_name, project_id, connector_type. Approval rules can use only tool_name and project_id. |
chat, embed, transcribe, speak | model, provider. provider is present only for external providers. |
deploy_model | project_id, model_id |
verify_model_integrity | model_id. A deny here refuses deploys of that model's unattested images. |
Orchestrate refuses to save a condition on a field the action never sends, so a typo cannot become a rule that never fires.
Add a policy
- Open Governance and, under Custom policies, choose New policy.
- Enter a name and say who asked for it and what it protects.
- Choose the action, the effect and the conditions.
- Choose Create policy.
OPA picks up custom policies every 5 to 15 seconds by default. Until it has, the policy shows Saved, but not in force yet. You can disable a policy without deleting it.
Test a request
Under Test a request, describe a request: the action and its fields. Choose Ask OPA. You see whether OPA would allow it, whether a tool call would need approval, and which custom policies matched. Testing writes nothing to the audit log.
Export and import
Choose Export JSON to download every custom policy as one file. Keep it in version control if you want.
To load a file, use Import policies from JSON. An import replaces the whole set: a policy that is not in the file is deleted. Preview the import first to see what it will create, update and delete. If any policy in the file is invalid, nothing changes.
{
"format": "vois-orchestrate.custom-policies/v1",
"policies": [
{
"name": "No chat with the partner provider",
"description": "Data protection decision.",
"effect": "deny",
"action": "chat",
"conditions": { "provider": ["partner"] },
"enabled": true
}
]
}
Every create, change, delete and import is recorded in the audit log.
In a multi-organization install
When Orchestrate hosts several organizations, an organization admin can write custom policies too. Their rules are filed under their organization and apply only to its own projects: the policy engine adds the project condition itself. Install-wide rules stay with the platform operators. See Multi-tenancy.
Examples
Allow a write tool in a project
To let agents in the support project send mail through Microsoft 365, add an Allow policy for call_tool with:
tool_name:o365_send_mailproject_id:support
The calls still wait for approval.
Require approval for a read tool
To make every call to a REST tool get_customer wait for a person, add a Require approval policy for call_tool with tool_name: get_customer.
Keep a model away from a project
To stop a project calling a model at all, restrict the model to the projects that may use it. See Model access. To stop a model being deployed into a project, add a Deny policy for deploy_model with project_id and model_id.
Stop agents calling each other
Add a Deny policy for call_tool with connector_type: agent. See Agents calling agents.
See the Governance API to manage policies from scripts.