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.
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:
| Role | Can |
|---|---|
| viewer | Read everything (logs, usage, settings); change nothing |
| developer | Deploy, configure, add databases, domains, backups and cron jobs |
| agent | Everything a developer can, with a spending limit, and subject to the project's rules for agents |
| admin | Also members, project settings, rules and deleting data |
| owner | Everything; 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:
cli keys create claude-code --role agent --days 90 --cap 10With the API:
POST /v1/projects/:id/keys{
"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
| Scope | Allows |
|---|---|
read | Every GET |
deploy | Deploys, rollbacks, cron runs, sandboxes, undo |
manage | Every other change: services, variables, domains, databases, settings |
secrets | Reading 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 getFORBIDDEN. - 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:
PATCH /v1/projects/:id/keys/:key{ "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:
cli keys revoke-allWith the API:
POST /v1/projects/:id/keys/revoke-allRules for agents in plain English
Instead of filling in settings, owners and admins write the rules as sentences.
Write and save your rules
- Open the project's Settings and find Rules for agents.
- 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."
- CLI reads each sentence back as what it will enforce. Check them.
- 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:
POST /v1/projects/:id/rules/preview{ "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:
| Setting | Example sentence | Effect |
|---|---|---|
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:
- The key's or member's total spend cap. Over it:
SPEND_CAP_EXCEEDED. - The project's daily limit for agents (
agentDailySpend). Agents' daily counters reset each UTC day. Over it:SPEND_CAP_EXCEEDED. - The project's monthly budget, if it's set to stop. Over it:
BUDGET_EXCEEDED. - 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:
cli agentsWith the API:
GET /v1/projects/:id/agentsThe owner can let agents above a score skip spending and production approvals:
PUT /v1/projects/:id/trust{ "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.