Policy

Every action an agent takes is a request for a capability, with a target (the tool, the path, the host, the server). The policy decides each request: allow it, deny it, or ask a person. An ask pauses the run until someone decides (durable runs); the security model explains the design.

How a request is decided

A deny rule that matches wins.
Otherwise an ask rule that matches: a person decides. An ask outranks an allow, so adding an allow rule to a profile does not lift that profile’s asks; remove the ask rule, or write your own policy.
Otherwise an allow rule that matches.
Otherwise the policy’s mode decides: permissive allows, interactive asks (reason unknown_capability), strict denies.

A decision is recorded in the run’s trace with its effect and reason_code (matched_allow, matched_ask, matched_deny, unknown_capability, approved when a person allowed an ask, and others). Two capabilities are decided when the agent connects, not during a run: mcp.server.start and mcp.server.connect. There is no run to pause then, so an ask on them fails the connection with ApprovalRequiredError; allow the servers you trust. The served agent’s policy also decides what an operator asks of OmniServe’s background API: background.task.* and background.run.*. A refusal there is an HTTP 403.

Writing a rule

from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

policy = build_default_policy("interactive-dev")
policy.rules.ask.append(
    PolicyRule(
        rule_id="ask_before_refunds",
        effect=PolicyEffect.ASK,
        capability="tool.local.call",
        target={"tool_name": "issue_refund"},
    )
)
agent_config = {"governance_config": {"enabled": True, "policy": policy}}

Or the whole policy as a dict:

agent_config = {
    "governance_config": {
        "enabled": True,
        "policy": {
            "name": "support-desk",
            "mode": "strict",  # anything no rule covers is denied
            "rules": {
                "allow": [{"rule_id": "tools", "capability": "tool.local.call"}],
                "ask": [
                    {
                        "rule_id": "refunds",
                        "capability": "tool.local.call",
                        "target": {"tool_name": "issue_refund"},
                    }
                ],
            },
        },
    }
}

Field	What it is
`rule_id`	Your name for the rule; it is recorded with every decision it makes.
`effect`	`allow`, `ask` or `deny` (the list it is in, for a dict policy).
`capability`	A capability below, or a glob: `workspace.files.`, `network.http.`, `*`.
`target`	Optional. Any of `tool_name`, `mcp_server`, `path`, `host`, `resource`; each a glob the request’s target must match.
`conditions`	Optional. `risk_level` (list), `provider`, `execution_surface`, `exclude_execution_surface` (list), `exclude_capability` (list of globs), `mcp_server`, `method`, `host`.
`constraints`	Optional. `approval_expires_seconds` (how long a person’s decision stays valid), `sandbox_required`, `audit_required`.

Capabilities

Capability	Allowing it lets the agent
`background.run.cancel`	Cancel a background run.
`background.run.start`	Start a background run.
`background.task.create`	Create a background task.
`background.task.delete`	Delete a background task.
`background.task.pause`	Pause a background task.
`background.task.resume`	Resume a background task.
`background.task.update`	Update a background task.
`code.run`	Run a program with run_code (code mode). Each tool it calls is decided on its own.
`filesystem.delete`	Delete a file on the host, outside the workspace. Target: path.
`filesystem.read`	Read a file on the host, outside the workspace. Target: path.
`filesystem.write`	Write a file on the host, outside the workspace. Target: path.
`mcp.server.connect`	Connect to a remote (SSE or streamable HTTP) MCP server. Decided when the agent connects, like mcp.server.start. Target: mcp_server.
`mcp.server.start`	Start a stdio MCP server process. Decided when the agent connects, outside any run: an ask cannot pause there, so it fails the connection. Target: mcp_server.
`network.http.delete`	Make an HTTP DELETE request. Target: host.
`network.http.get`	Make an HTTP GET request. Target: host.
`network.http.head`	Make an HTTP HEAD request. Target: host.
`network.http.patch`	Make an HTTP PATCH request. Target: host.
`network.http.post`	Make an HTTP POST request. Target: host.
`network.http.put`	Make an HTTP PUT request. Target: host.
`package.install`	Install a package. Target: resource (the package), host (the index).
`process.exec`	Run a command: in the sandbox (execution surface sandbox), or on the host with the local provider (surface host). Target: resource (the command’s name).
`sandbox.environment.set`	Set plain environment variables in the sandbox (their names are in the request, not the target).
`sandbox.execute`	Call the execute tool. Each command it runs is then decided as process.exec.
`sandbox.filesystem.configure`	Give the sandbox read, write or deny path rules. Target: path.
`sandbox.filesystem.cwd`	Run a command in a working directory the manifest or call names. Target: path.
`sandbox.filesystem.mount`	Mount a host directory into the sandbox. Target: path, resource (the source).
`sandbox.image.use`	Start the sandbox from an image named in the manifest. Target: resource (the image).
`sandbox.network.configure`	Turn the sandbox’s network on, or allow or deny a host in it. Target: host.
`sandbox.resources.set`	Set the sandbox’s CPU, memory, disk or time limits.
`secret.read`	Read a secret’s value.
`secret.use`	Use a secret without reading it: brokered into a command, never shown to the model.
`skill.files.read`	Read a skill’s instructions and files.
`skill.script.run`	Run a skill’s script (run_skill_script): code runs.
`subagent.spawn`	Start a sub-agent: delegate_<name> to an agent in sub_agents, or spawn_subagents. Target: resource (the agent’s name).
`tool.local.call`	Call one of your Python tools (local_tools), or a sub-agent’s delegate_<name> tool. Target: tool_name.
`tool.mcp.call`	Call a tool on an MCP server. Target: mcp_server, tool_name.
`workspace.artifacts.call`	Any other artifact tool.
`workspace.artifacts.read`	Read a saved tool result: read_artifact, tail_artifact, search_artifact, list_artifacts.
`workspace.files.call`	Any other workspace file tool.
`workspace.files.clear`	Delete every file in the workspace (clear_files).
`workspace.files.delete`	Delete a workspace file (delete_file). Target: path.
`workspace.files.move`	Move or rename a workspace file (move_file). Target: path.
`workspace.files.read`	Read the workspace: ls, read_file, glob, grep. Target: path.
`workspace.files.write`	Write in the workspace: write_file, edit_file, insert_file. Target: path.

Built-in profiles

Each profile below is build_default_policy(name). Start from one and add rules, or write your own policy.

`permissive-dev`

Mode permissive.

Effect	Rule	Capability	Conditions
deny	`deny_credential_or_system_prompt_flow`	`*`	`{'data_classes': ['credential', 'system_prompt']}`
deny	`deny_raw_secret_read`	`secret.read`
deny	`deny_unconfigured_secret_broker_use`	`secret.use`
deny	`deny_unrestricted_process_exec`	`process.exec`	`{'exclude_execution_surface': ['sandbox']}`
deny	`deny_unrestricted_host_filesystem_access`	`filesystem.*`
deny	`deny_unrestricted_network_egress`	`network.*`
deny	`deny_unrestricted_package_install`	`package.install`
ask	`ask_sandbox_network`	`sandbox.network.configure`
ask	`ask_sandbox_host_mount`	`sandbox.filesystem.mount`
allow	`allow_sandboxed_execution`	`process.exec`	`{'execution_surface': 'sandbox'}`
allow	`allow_sandbox_setup`	`sandbox.*`
allow	`allow_skill_scripts`	`skill.*`
allow	`allow_code_mode`	`code.*`
allow	`allow_local_dev_workspace`	`workspace.*`
allow	`allow_local_tools`	`tool.local.call`
allow	`allow_memory_and_telemetry`	`memory.*`
allow	`allow_telemetry`	`telemetry.*`
allow	`allow_subagent_spawn`	`subagent.*`
allow	`allow_background_execution`	`background.*`

`interactive-dev`

Mode interactive.

Effect	Rule	Capability	Conditions
deny	`deny_credential_or_system_prompt_flow`	`*`	`{'data_classes': ['credential', 'system_prompt']}`
deny	`deny_raw_secret_read`	`secret.read`
ask	`ask_process_exec`	`process.*`	`{'exclude_execution_surface': ['sandbox']}`
ask	`ask_sandbox_network`	`sandbox.network.configure`
ask	`ask_sandbox_host_mount`	`sandbox.filesystem.mount`
ask	`ask_network_egress`	`network.*`
ask	`ask_package_install`	`package.install`
ask	`ask_secret_broker_use`	`secret.use`
ask	`ask_mcp_tool_call`	`tool.mcp.call`
ask	`ask_mcp_server_start`	`mcp.server.*`
ask	`ask_subagent_spawn`	`subagent.*`
ask	`ask_background_execution`	`background.*`
ask	`ask_high_risk`	`*`	`{'risk_level': ['high', 'critical'], 'exclude_execution_surface': ['sandbox'], 'exclude_capability': ['skill.script.run']}`
allow	`allow_sandboxed_execution`	`process.exec`	`{'execution_surface': 'sandbox'}`
allow	`allow_sandbox_setup`	`sandbox.*`
allow	`allow_skill_scripts`	`skill.*`
allow	`allow_code_mode`	`code.*`
allow	`allow_local_tools`	`tool.local.call`
allow	`allow_workspace`	`workspace.*`
allow	`allow_memory`	`memory.*`
allow	`allow_telemetry`	`telemetry.*`

`strict-production`

Mode strict.

Effect	Rule	Capability	Conditions
deny	`deny_credential_or_system_prompt_flow`	`*`	`{'data_classes': ['credential', 'system_prompt']}`
deny	`deny_raw_secret_read`	`secret.read`
allow	`allow_governance_telemetry`	`telemetry.governance.*`

Get Started

Build

Make It Safe

Run It

See and Improve

How It Works

Reference

HTTP API (OmniServe)

Releases

Policy

Policy

How a request is decided

Writing a rule

Capabilities

Built-in profiles

`permissive-dev`

`interactive-dev`

`strict-production`

​Policy

​How a request is decided

​Writing a rule

​Capabilities

​Built-in profiles

​permissive-dev

​interactive-dev

​strict-production

Policy

How a request is decided

Writing a rule

Capabilities

Built-in profiles

`permissive-dev`

`interactive-dev`

`strict-production`