A capability policy decides what an API key may do on the systems it can reach: for each capability, whether it's allowed, needs a person's approval, goes to Guardian, or is denied. Three policies come built in, and you can create your own. You then attach a policy to an API key's access rules.

Before you start

An admin role.
An idea of what the key's task needs. For what each capability allows, see Automation capabilities.

The Capability Policies screen

Go to Admin > Capability Policies.

The Capability Policies list with Built-in, Gates, Keys and Actions numbered 1 to 4

Built-in: the three policies that come with every account.
Gates: what the policy restricts, in short.
Keys: how many API keys use the policy.
Actions: create your own policy.

The built-in policies

Full access: everything is allowed, with no approval. For machines an agent is trusted to run unattended, such as test VMs.
Approval for risky: everything is allowed except the six risky capabilities, which need a person's approval. A good default for anything that matters.
Read only: the agent can look but not change anything. The 9 capabilities that change something are denied.

If one of these fits, skip to Step 4 and attach it to your key.

Step 1 - Name the policy

Click Actions > Create policy.

The Create Capability Policy panel with name, description, bulk modes, Guardian note, Risky badge and the four modes numbered 1 to 6

Enter a Name.
Enter a Description saying what the policy is for.
Set every capability at once with Allow all, Require approval for risky or Deny all. Start from whichever is closest, then change only the capabilities you need to.
If Guardian isn't set up, this note appears. Capabilities set to Guardian then ask a person instead.
Risky marks the six capabilities that change or control the system.
The four modes, shown for each capability. See Step 2.

Step 2 - Choose a mode for each capability

Allowed: it runs.
Guardian: an AI reviewer checks each request and approves it, denies it, or passes it to a person. See Secure the account.
Human approval: a person must approve it first. See Approve a capability request.
Denied: it never runs.

NOTE: Screenshots, the keyboard and the mouse aren't risky, so Require approval for risky still lets an agent see the screen and use the mouse and keyboard freely. If you want those checked too, set them to Guardian or Human approval.

Step 3 - Set the session gate

Scroll to the bottom of the list:

The Session gate and session.open entry in the policy editor

Session gate: controls whether the key can open a session at all on the systems a rule covers.
session.open: leave it Allowed for normal use. Set it to Denied to make those systems unreachable for the key.

Click Create.

Step 4 - Attach the policy to an API key

Go to Admin > API Keys and create or edit a key.
Under System access, choose which systems the rule covers.
In the rule's second box, choose your policy.
Click Create or Save.

A key can have several rules, each with a different policy, such as Read only for one production system and Approval for risky for everything else. See API keys and their permissions.

Check it worked

On Admin > Capability Policies, the policy's Keys count has gone up.
With the key, run hv capabilities check in a session. It lists what's allowed, what needs approval and what's denied.
Try a gated capability. It should wait for approval instead of running.

Tips

Allow only what the task needs. Most monitoring and testing needs nothing risky. See the task list in Automation capabilities.
Don't gate more than people can review. If approvals pile up, people start approving without reading. Gate only what matters, such as shell.exec, or let Guardian take the routine requests.
Name policies after what they're for, such as CI test VMs or Helpdesk agent, so the right one is easy to pick when you create a key.

Create and use capability policies