AI control

AI control is a switch in Settings that decides what agents may do on this instance. It is enforced on the control plane for 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, or the built-in assistant token (agent name ai-assistant). 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

Mode	What an agent may do
off	Nothing. Every request answers 403 "agent access is disabled by an administrator".
observe	The read ability only, in any environment. No secrets, no changes.
operate	read, read:sensitive, write and deploy. Never root, never write:sensitive (secrets, backups, instance settings). On an app or database, only if its environment kind is allowed.
admin	Any ability the token holds, with the same environment limit. Needs APP_EXPERIMENTAL=ai-control. Without the flag it behaves as operate.

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:

levelrail-cli ai-control status
levelrail-cli ai-control set --mode operate --env-kinds dev,test,uat,preview

--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:

levelrail-cli ai-control set --mode operate --env-kinds dev,test,uat,preview,custom

Revoke agent tokens

levelrail-cli ai-control revoke-agents --yes

This revokes every token that has an agent name and reports how many. The built-in assistant token is not revoked, because that would break the in-app assistant. Set the mode to off to stop it 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. To see one agent:

levelrail-cli audit-log --agent my-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

Message	Meaning
agent access is disabled by an administrator	The mode is off.
agent access is limited by the current AI control mode	The mode does not allow this ability, for example a write in observe or root in operate.
agent access is not allowed in this environment	The resource's environment kind is not in the allowed list.
agents cannot approve deploys, a human must	Approvals always need a person.
agents cannot change AI control settings	Only a person with root can change the switch.

API

Method	Path	Ability
GET	/api/v1/settings/ai-control	read
PUT	/api/v1/settings/ai-control	root
POST	/api/v1/settings/ai-control/revoke-agent-tokens	root

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.