Skip to main content
AI control is a switch in Settings that decides what agents may do on this instance. The control plane enforces it on every request, so it does not depend on the agent, the MCP client or the token’s own abilities. The page is always visible because it is the guardrail.

​
What counts as an agent

An agent is an API token that has an agent name, including the short-lived token the in-app assistant mints for each chat turn (agent name ai-assistant). That turn token is owned by the person who sent the message and carries only their abilities and IAM policies, so the mode below narrows what the assistant may do on their behalf, never widens it. Agent tokens can only be created by a signed-in person, never by another token. AI control does not govern:
  • people signed in with a session,
  • API tokens that have no agent name (they are limited only by their abilities and IAM policies).
So give every automation or AI client token an agent name when you create it. Otherwise this switch cannot see it.

​
Modes

In operate and admin:
  • An agent can never approve a deploy approval, a pipeline approval or a preview approval. A person must.
  • An agent can never change AI control settings or revoke tokens.
  • Moving or deploying into a protected environment still creates an approval that a person decides.
The environment limit is a list of kinds: dev, test, uat, production, preview, custom. The default allowed list is dev, test, uat and preview. A resource with no environment counts as kind custom, which is not allowed by default.

​
Set the mode

In the dashboard: Settings, AI control. Pick a mode and the allowed kinds. Pause all agents sets the mode to off in one click. From the CLI:
--env-kinds is optional: leave it out and the current list is kept. --mode is required. To let agents act on resources with no environment, add custom:

​
Revoke agent tokens

This revokes every token that has an agent name and reports how many. The in-app assistant’s per-turn tokens are skipped: each one is already revoked when its turn ends. Set the mode to off to stop the assistant instead.

​
Defaults and upgrades

  • A fresh instance starts in off. The in-app assistant needs a mode set before it works.
  • An instance that already had live agent tokens when it was upgraded starts in operate, so existing agents keep working.

​
Audit

Every request an agent makes that this switch refuses is written to the audit log with the agent name and the reason. Changes to the setting and token revocations are audited too. Requests from the in-app assistant also record on_behalf_of, the person whose chat turn made them. To see one agent:
The AI control page also links to the audit log filtered by agent.

​
MCP

The MCP server reads the mode each time a client asks for its tool list, and hides what the mode would refuse, but only when its own token is an agent: off shows only ai_control_status, observe shows read tools, operate and admin show everything. A token with no agent name is not governed by this switch, so its tool list is never trimmed. This only tidies the list. The control plane enforces the mode whatever the client does.

​
Error messages

​
API

GET also reports caller_is_agent, whether the token making the request is an agent. PUT takes {"mode": "...", "allowed_env_kinds": [...]} and answers 400 for admin unless the ai-control flag is on.

​
Next steps

AI assistant integration

Scope an API token for an MCP client or an AI agent.

Working with AI agents

Build an agent that deploys and monitors your apps.
Last modified on October 12, 2026