Skip to content
Controller AI Controller AI Controller AI Docs

Connect your coding agent

Controller AI is built to be operated by the coding agent you already use — Claude Code, Codex, Cursor, or any terminal-based agent. The agent connects once, gets a verified set of skills, and from then on builds agents and automations on your account through the cai CLI.

Start with one prompt

Section titled “Start with one prompt”

Open Connect your agent, copy the setup prompt, and paste it into your coding agent:

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

The agent will:

  1. Verify Node.js 20 or newer and npm.
  2. Install or update the cai command globally.
  3. Open Controller AI in your browser for authorization.
  4. Fetch and verify the current Controller AI skills.
  5. Read the entry skill and route your request to an agent, an automation, or both — asking only when the outcome is unclear.

Setup installs the CLI and personal skills. It does not add Controller AI files to your current repository, and your account password never enters the agent conversation.

Manual setup

Section titled “Manual setup”
Terminal window
npm install -g @controllerai/cli@latest
cai connect

cai connect opens your browser and shows the same short verification code in both places. Confirm the codes match, approve the connection, and return to the terminal. On a headless or remote machine, use cai auth login --no-open and open the printed URL yourself.

Check the result at any time:

Terminal window
cai doctor
cai skills status

cai doctor reports authentication, skill integrity, and whether a newer CLI version is available. When it says a newer version exists, upgrade before continuing — new versions carry fixes the skills assume:

Terminal window
npm install -g @controllerai/cli@latest
cai skills update

What the authorization actually grants

Section titled “What the authorization actually grants”

Approving the browser prompt mints a revocable machine credential (prefixed cai_) scoped to your account. It is stored in the CLI’s config on that machine — not in the agent’s conversation. Your password and provider credentials are never part of the flow: anything that needs a login (like connecting Gmail or Slack) always happens in your browser, not in the terminal.

You can see and revoke every connected machine at any time under Settings → Connected sessions in the app. Revoking a session immediately cuts off that machine’s CLI access.

cai auth status shows which account the current machine is authorized against; cai auth logout removes the local credential.

The managed skills

Section titled “The managed skills”

cai connect installs 11 managed skills — versioned instruction packages that teach a coding agent how the platform actually works: workflows, node configuration, expressions, flow control, triggers, data, AI nodes, integration actions, agents, runs, and the entry skill that routes between them.

Skills are the procedural manual; these docs are the reference for concepts, contracts, and consequences. Your agent loads skills on demand while it works.

The skill installer is deliberately paranoid:

  • Every install verifies the manifest, CLI compatibility, file sizes, and SHA-256 digests before replacing anything.
  • Only Controller AI-managed skill copies are ever replaced. A same-named skill you wrote yourself is never touched unless you pass --force.
  • If the hosted feed is unreachable, an intact current set is kept as-is; the bundled fallback fills in only missing or damaged skills.
  • Invalid manifests and integrity failures stop the install — nothing partial is written.

cai skills status shows what is installed and whether it matches the current hosted set. cai skills update refreshes the managed set without reinstalling the CLI.

Where things are pinned

Section titled “Where things are pinned”

The CLI remembers which workflow you are working on. cai use <workflowId> writes the pin both globally and to a .cai.json file in the current project directory. The project pin wins, so two terminal sessions in different directories can safely work on different workflows. Environment variables (CAI_TOKEN, CAI_CONFIG) override both for CI-style use.

Next steps

Section titled “Next steps”