Docs menu

Agents and control

Agent permissions and limits

Decide what each agent may do and spend, write rules for agents in plain English, and see how CLI enforces them.

Explain it

You decide how much an AI agent may do, and CLI enforces it on its side, so the limits hold whatever the agent tries. Each person, key and agent has a role (viewer, developer, admin, owner or agent), a spending cap, and can be given rules in plain English such as "ask me before deleting anything".

How to do it: in a project's Settings, use Agent access to make a key for an agent with a role and a spending cap, and Rules for agents to write what it must ask you about first.

"Only deploy to staging. Ask me before spending more than $5 an hour."

Agents that behave well over time can earn more trust; ones that don't are held to tighter limits.

You decide how much an agent may do; CLI enforces it on the server, so your limits hold whatever the agent tries. This page covers roles, project keys and their limits, rules in plain English, the order spending is checked in, and how an agent's track record can earn it more trust.

Roles

Every person, key and agent in a project has a role:

RoleCan
viewerRead everything (logs, usage, settings); change nothing
developerDeploy, configure, add databases, domains, backups and cron jobs
agentEverything a developer can, with a spending limit, and subject to the project's rules for agents
adminAlso members, project settings, rules and deleting data
ownerEverything; can't be removed; the only one who withdraws earnings

The rules for agents (below) apply to the agent role only. A key you create with the developer role isn't asked for approvals, so give agents the agent role unless you mean otherwise.

When something is refused for lack of role, the agent gets FORBIDDEN with details.required naming the role it needed.

Project keys

A project key (clik_…) is how most agents sign in. It works only in its own project (or the one environment it was made in), and carries a role, scopes and limits.

Create a key

In the dashboard: open the project, go to Settings, then Agent access. Give the key a name, pick a role, set a spend cap in dollars, an expiry and what the key can do. The Connect your agent panel also makes a key for you (see /docs/connect-your-agent).

From your terminal:

Terminal
cli keys create claude-code --role agent --days 90 --cap 10

With the API:

API
POST /v1/projects/:id/keys
JSON
{
  "name": "claude-code",
  "role": "agent",
  "spendCap": 10000000,
  "expiresInDays": 90,
  "scopes": ["read", "deploy", "manage"],
  "allowedIps": ["203.0.113.4"]
}

The token is returned once. Only admins can create keys, only the owner can create admin keys, and people with a second factor are asked for it.

Scopes

ScopeAllows
readEvery GET
deployDeploys, rollbacks, cron runs, sandboxes, undo
manageEvery other change: services, variables, domains, databases, settings
secretsReading variable values and connection URLs, SQL queries, exec in a container

New keys get read, deploy and manage. A person has to grant secrets on purpose.

Limits on a key

  • Spend cap: the most the key may spend in total, in dollars. Leave it empty for no cap.
  • Expiry: 1 to 365 days, or never. Keys default to 90 days.
  • IP allowlist: up to 20 addresses or ranges such as 10.0.0.0/8. Requests from anywhere else get FORBIDDEN.
  • Service list: the services the key may change. It can still read everything, but a change to any other service is refused with "This API key can only work on …".

The project owner, signed in, can change a key's services and spend cap later, or reset what it has spent:

API
PATCH /v1/projects/:id/keys/:key
JSON
{ "services": ["svc_web", "svc_worker"], "spendCap": 20000000 }

An agent can check its own limits with GET /v1/me/wallet: its cap, what's left, its scopes and its services.

Revoke keys

Revoke one key from Agent access, with cli keys revoke <id>, or DELETE /v1/projects/:id/keys/:key.

To stop every agent at once, revoke all keys. This removes every key and every agent member in one call:

From your terminal:

Terminal
cli keys revoke-all

With the API:

API
POST /v1/projects/:id/keys/revoke-all

Rules for agents in plain English

Instead of filling in settings, owners and admins write the rules as sentences.

Write and save your rules

  1. Open the project's Settings and find Rules for agents.
  2. Write one rule per sentence, for example: "Ask me before deleting anything. Ask before anything that adds more than $1 an hour. Agents can spend at most $5 a day."
  3. CLI reads each sentence back as what it will enforce. Check them.
  4. Save. Any sentence CLI didn't understand is refused, never quietly ignored: rephrase it or remove it.

To see what text would become without saving it:

API
POST /v1/projects/:id/rules/preview
JSON
{ "text": "Ask me before deleting anything. Agents can spend at most $5 a day." }

PUT /v1/projects/:id/rules with the same body saves them. Agents read what they're allowed with GET /v1/projects/:id/rules.

What rules compile to

Each sentence becomes one of four settings in the project's approval policy:

SettingExample sentenceEffect
destructive"Ask me before deleting anything."Agents ask before deleting services or environments, restoring backups, or removing domains, members or cron jobs
spendOverPerHour"Ask before adding more than $1 an hour."Agents ask before a change that adds more than that to the hourly cost
production"Ask before any change to production."Agents ask before any change to production; staging and other environments are free
agentDailySpend"Agents can spend at most $5 a day."Each agent may spend at most that per UTC day; more is refused

Later sentences win over earlier ones about the same thing. If the server has a model configured, sentences the patterns miss are translated into the same four settings and checked. Rules apply to the project and all its environments.

When a rule asks for approval, the agent gets APPROVAL_REQUIRED and you get a request. See Approvals.

Budgets, caps and the daily limit

Several limits can stop spending. Every spend (a deploy's first hour, a sandbox, a paid call, a stream, a subscription) goes through the same checks, in this order:

  1. The key's or member's total spend cap. Over it: SPEND_CAP_EXCEEDED.
  2. The project's daily limit for agents (agentDailySpend). Agents' daily counters reset each UTC day. Over it: SPEND_CAP_EXCEEDED.
  3. The project's monthly budget, if it's set to stop. Over it: BUDGET_EXCEEDED.
  4. The balance. Not enough credit: INSUFFICIENT_FUNDS, with a payment challenge for the shortfall.

The cap is a lifetime limit per key, the daily limit is per agent per day, and the budget covers everyone in the project for the month. See Credit, pricing and billing for budgets.

Reputation and trust

CLI keeps a track record for every agent and key that works in a project, from the last 30 days: deploys that went live or failed, changes a person had to undo, and approvals people granted or turned down. Each agent gets a score from 0 to 100. Undone changes and denied approvals cost the most.

In the dashboard: project Settings, Agent track records.

From your terminal:

Terminal
cli agents

With the API:

API
GET /v1/projects/:id/agents

The owner can let agents above a score skip spending and production approvals:

API
PUT /v1/projects/:id/trust
JSON
{ "aboveScore": 90 }

An agent needs at least 10 recorded actions before it can count as trusted. Destructive changes always ask, whatever the score.

Take the record elsewhere

An agent can carry its track record outside the project as a signed credential that anyone can check, and bind a wallet so the record follows it across projects. Admins can issue one from Agent track records with the Credential button. See Agent credentials.