Choose Your Setup

Start with Home → Build for me, or connect your assistant through Connect → Build with your coding agent. The in-product builder is already configured. External assistants need setup and account authorization. If Build for me reports empty usage credit, open Settings → Billing, add credit, and retry.

Choose where you want to work

Where you work	First step	Setup page
Controller AI app	Describe Support helper on Home; select Build for me.	First agent
Claude Code	Run cai agent setup --client claude-code --json.	Claude Code
Claude web, Desktop, or Cowork	Follow the manual connection steps.	Claude app
ChatGPT	Follow the manual connection steps.	ChatGPT
Codex	Run cai agent setup --client codex --json.	Codex
Cursor	Run cai agent setup --client cursor --json; apply its printed configuration.	Cursor and other hosts
Another remote MCP host	Add https://mcp.getcontroller.ai/mcp using Streamable HTTP and OAuth with PKCE S256.	Other hosts

If cai is not installed, give your coding assistant the app’s setup prompt:

Read https://getcontroller.ai/start.md, connect this coding agent to my Controller AI account, and help me build an agent or automation.

What is already configured in the app?

With the in-product builder, you get help assembling agent drafts and workflows. Its narrower permissions leave agent testing and publication to you. A Controller AI agent is what you build. Your assistant helps build it. A plugin packages access and skills, rather than adding a product building block.

Connect the intended account

Choose CLI or MCP for the task. Their authentication is separate. A CLI credential does not complete MCP OAuth login. These setup commands need no workflow selection.

CLI: new users first run cai signup --json. If signup is disabled, register an account, then continue. Run these commands to update only Codex skills, connect your account, and check its identity.

cai connect --target codex --json
cai auth status --json

Before creating Support helper, check data.user.email, data.user.id, and data.user.organizationId.

Without a target, cai connect defaults to --target auto. It updates every detected Codex, Claude, Cursor, and Copilot skill home. If none exists, it falls back to .agents. Skills are written before authentication and remain after a later failure.

To claim a signup account, run cai signup email <address> --json with the owner’s unregistered email. Then run cai signup verify <code> --json with the emailed code. See Manage account usage.

MCP: choose My Controller account to sign in or sign up, or Separate agent account to create or continue without email or password. A separate account has its own workspace. When you claim it, you keep that workspace and cannot merge it into an existing account. Use an email not already registered. By default, its monthly plan allowance is capped at $1. Claiming restores the plan allowance and enables email recovery.

To build, choose Allow full access. Continue read-only permits inspection. Call account_status with {} and check its result data. The account.kind value is member, unclaimed agent, or claimed. To build, you need account.accessMode: "full" and controller:full in grantedScopes. Check the returned user and usage before creating anything.

If the CLI account is wrong, run cai auth login --json, then cai auth status --json. The connect command reuses valid credentials. For MCP, reconnect through the host, select the intended account, and repeat account_status with {}.

Check that setup is ready

Run these checks to see which setup steps remain and which assistants were detected.

cai agent setup --status --json
cai doctor --json

Inspect the remaining steps and detected assistants. Even when you select an assistant with --client, setup skips it if it is undetected. When changes are planned, setup prints them. It prompts only in an interactive terminal. Without an interactive terminal or --yes, it exits with SETUP_CONFIRMATION_REQUIRED.

Run this command to approve the printed Codex setup changes and receive the setup result.

cai agent setup --client codex --yes --json

If authorization_required appears, show its url immediately. Even in JSON mode, setup or login can wait for browser authorization. After these event lines, parse the last stdout line as the final result. --yes approves setup changes, not browser authorization.

With MCP, use account_status with {} to check readiness. For guidance, call guide_list with {}, then guide_get with {"name":"controllerai-start"}.

What should you do next?

Build Support helper and check its first policy answer.