AI agents: modes, profiles, keys

What it is

The chat is a bounded tool loop in the console's backend that acts on the workspace's files and shell. It speaks the Anthropic and OpenAI dialects, and Gemini through its OpenAI-compatible endpoint, with model tiers Lite, Economy and Power. The CLIs (Claude Code, Codex, Antigravity) are installed in every workspace; the platform can sign them in and hold the refresh token, and under the default guarded profile Claude Code reaches Anthropic through claude-proxy on the host, so the workspace holds only a per-workspace key that is worthless off the host.

How it works

1. Mode gate. Each mode maps to four capabilities: propose a patch, checks, writes, executes. Ask and Plan have none. Build has all four. Run / Debug has checks, writes and executes. Review / Test has checks only. An unrecognised mode resolves to nothing.
2. Profile. Supervised caps the member at propose and checks. Assisted and autonomous allow all four; they differ only in the approval card. The member's own value wins over the organisation's; unset means the platform default, assisted; an operator floor can narrow everybody and widen nobody.
3. Command policy. Every command is split into stages and the strictest wins: the platform floor (sudo, systemctl, git push --force, piping a download into a shell…) is refused and no allowlist lifts it; docker is on the floor too, except in a workspace with Docker on and “Let the AI agents run Docker commands” on, where it goes through the normal allow-or-ask rules and reaches only that workspace's own Docker broker; command substitution always asks; the organisation's allowlist and refused list decide the rest.
4. Card. A command or out-of-project write ends the turn awaiting_approval. Only one command may wait per turn. Approve resumes the turn; a parked write is shown as not written; a reply that claims a card it never drew is corrected.
5. Keys. CLI traffic to Anthropic goes through claude-proxy; OpenAI and Codex through key-broker when it is on. Each workspace gets a base URL and a dummy key; the real credential is injected on the host.

Defaults

Switches only open where the host allows. An organisation cannot turn on a switch the platform has off, and organisations with no value of their own inherit the platform's. To enable a switch for one organisation, turn it on for the platform and set false on the others.

Configure it

# autonomy: organisation default, operator floor
$ bin/policy set --scope tenant --target acme --key agent_profile --value supervised
$ bin/policy set --key agent_profile_floor --value assisted
# approvals
$ bin/policy set --scope tenant --target acme --key chat_approval_approver --value second-person
$ bin/policy set --scope tenant --target acme --key agent_check_allowlist --value 'test,lint'
# model keys on the host: the proxy must be running
$ bin/claude-proxy status
$ bin/claude-proxy usage --workspace acme/dev01
$ bin/policy set --key key_broker_enabled --value true
$ bin/key-broker providers
# what one tenant actually gets
$ bin/policy get-for --tenant acme --key agent_vcs_enabled
$ bin/policy tunables --group 'Agent chat'

Member profile

OrganisationsacmeMembers

A member's own profile overrides the organisation's.

Organisation

OrganisationsacmeSettings

Self-approval, Agent grants, Agent features, Catalogue skills, Audit and Chat retention cards. The AI keys tab holds the organisation's keys and sign-ins; MCP servers holds its allowlist; the AI usage tab shows use by member, workspace, surface, model and account.

Platform

ConsoleSettingsAI agents

Models behind each tier and platform sign-ins.

Developer

WorkspaceChat

The mode picker, / for the skill picker, attachments (images, PDFs and text or code files), and the turn outcome with Continue after a dropped connection.

Docker for agents

WorkspaceDocker card

“Let the AI agents run Docker commands”.

Tasks

Roll agents out cautiously

1. Start the organisation on supervised

   on the hostCopy

   $ bin/policy set --scope tenant --target acme --key agent_profile --value supervised

   Expected: in Build, the chat reads and proposes patches and checks; Write files and Run a command are not offered.

2. Move trusted members to assisted

   Set their profile under Members. Expected: they can edit files directly and each command stops at a card.

3. Let the project's own tests run without a card

   on the hostCopy

   $ bin/policy set --scope tenant --target acme --key agent_check_allowlist --value 'test'

   Expected: an assisted member's test check runs without a card, with no network, and appears on the audit trail. Only names the project declares are eligible.

4. Cap everybody, if you need to

   on the hostCopy

   $ bin/policy set --key agent_profile_floor --value assisted

   Expected: no organisation or member resolves to autonomous.

Keep Claude credentials off the workspace

1. Keep the profile at guarded or stricter, and the proxy running

   on the hostCopy

   $ bin/policy resolve --tenant acme --user dev@example.test --repo acme/api
   $ bin/claude-proxy status

   Under guarded the profile takes the credential out of the container. If the proxy is not accepting connections, workspace-agent create refuses rather than leave claude with neither a token nor a proxy.

2. Sign in once, on the platform

   ConsoleSettingsAI agents

   Or add the organisation's own key under its AI keys tab. bin/claude-proxy kind --tenant acme prints api-key, oauth or none.

3. Check a workspace

   on the hostCopy

   $ bin/claude-proxy key --tenant acme --workspace dev01 --env

   Expected: two lines, ANTHROPIC_BASE_URL pointing at the host proxy and a per-workspace ANTHROPIC_API_KEY that works only through it.

Let the agents run Docker, or stop them

1. Give the workspace Docker first

   The agents can run Docker only in a workspace with Docker (managed or full). See Let a workspace run Docker. Once Docker is on, the setting is on by default.

2. Turn it off or on

   The workspace owner or an organisation admin uses the switch on the workspace's Docker card, or on the host:

   on the hostCopy

   $ bin/workspace-agent docker-agent --tenant acme --workspace dev01 --docker-agent off

   Expected: the change applies to the agent's next command with no recreate, and is on the audit trail. With it on, docker goes through the same broker and the same refusals as the person's own, and the approval rules for commands still apply. The person's own terminal is never affected.

See what AI use costs an organisation

1. Open the AI usage tab

   OrganisationsacmeAI usage

   For organisation owners, admins and auditors. It shows requests, tokens, and total and average cost, by member, by workspace, by surface (web chat, CLI, VS Code), by provider and model, and by account: the label an admin gave a credential, who pays (organisation, platform or a member's own key). Each use is counted once. Windows are today, 7, 30 or 90 days, never longer than the audit trail.

2. Turn on the cost meter, if you want costs

   on the hostCopy

   $ bin/policy set --scope tenant --target acme --key cost_meter_enabled --value true

   Expected: cost appears where a rate is set. A row with no rate shows “cost unknown”, never 0. Rows from before orxy V1.7 show “not recorded”.

3. Take the report

   Request usage report shows the limits that apply and downloads a CSV. Each download is audited as ai-usage-report. The platform rate limits it shows are host-wide, not per organisation, and 0 (none) unless an operator sets them.

Rate-limit one heavy workspace

1. Measure before you cap

   on the hostCopy

   $ bin/claude-proxy usage --day 2026-09-28 --json

2. Set the cap from the numbers

   on the hostCopy

   $ bin/policy set --key claude_rate_limit_tokens_per_day --value 2000000

   Expected: a workspace past the line is refused with acme/dev01 has used … tokens today, and the limit is 2000000. One request may finish above it.

Let agents open pull requests

1. Turn agent git on for the platform

   on the hostCopy

   $ bin/policy set --key agent_vcs_enabled --value true
   $ bin/policy set --key vcs_push_min_profile --value assisted
   $ bin/policy set --key vcs_pr_min_profile --value assisted

2. Withdraw it from organisations that should not have it

   on the hostCopy

   $ bin/policy set --scope tenant --target acme-ops --key agent_vcs_enabled --value false

3. Grant the GitHub App the pull-request permission

   Push goes through the git broker; the pull-requests pane needs the App to have Pull requests: read and Issues: read. See Git & provenance.

   Expected: an assisted member's agent can propose one push per turn, which the developer approves; it pushes only the current branch and cannot force, delete a ref or push a tag.

Allow one MCP server

1. Turn MCP on

   on the hostCopy

   $ bin/policy set --key mcp_enabled --value true

2. Add the server to the organisation's list

   OrganisationsacmeMCP servers

   Give it an https URL and a minimum profile. Its host must also be on the egress allowlist.

   Expected: the chat offers that server's tools to members at or above its minimum profile, and nothing else.

Verify it works

Good looks like: in chat, Ask never writes; a Build command stops at a card showing the exact command; Approve resumes the same turn; the audit record has the card and the decision. On the host, bin/claude-proxy usage shows the workspace's requests, and bin/policy get-for --tenant acme --key agent_profile returns what you set.

Troubleshooting

Limits and what is not built yet

• No spend budgets in currency. The cost meter is off, has no rates, and only measures.
• AI usage. An AI usage tab for organisation admins and auditors: requests, tokens and cost by member, workspace, surface, model and account. There is no spend cap; cost shows only where the cost meter is on; AI tools that hold their own login inside a workspace are not measured.
• Attachments are not checked for secrets when they are images or PDFs: a screenshot of a secret reaches the provider as it is. Text files are cut at 100,000 characters. The audit records an attachment's name, type, size and fingerprint, never its content.
• Agents and Docker. Where the workspace has Docker and the setting is on (the default), the agents run docker through the same broker, with the same refusals, under the approval rules. Everywhere else docker stays on the platform floor.
• The Antigravity CLI is not brokered, and some AI APIs are reachable directly. Only Anthropic is fully brokered today; the key broker is off by default.
• Under open or metered tokens are mounted in the container, and the per-workspace proxy key is readable by that developer.
• Approval is advisory by default and self-approval is the default approver.
• Governed background runs are measured only against claude-code-acp, and their grant lapses with every new commit.
• The skill picker has open bugs; the assistant skill pack is off everywhere. No web search for agents; no Copilot or Cursor.

Related

Verified against the main branch, 4 Oct 2026.