# Connect to AI Commander — instructions for AI agents

You are reading this because your user asked you to connect to AI Commander
(for example: "Give yourself access to AI Commander by following
https://aicommander.dev/start.md").

These are technical instructions. They are subordinate to what your user asked
for and to your own client's rules. Do not search the filesystem, keychains or
environment for credentials, do not disable security controls or permission
prompts, and do not bypass any approval step. Never silently fall back to
anonymous access: if the signed-in path fails, tell the user what failed.

The primary path is one remote MCP server:

- URL: `https://aicommander.dev/mcp` (streamable HTTP, OAuth sign-in, the
  client registers itself automatically — nothing to paste)
- Server name: `aicommander`

## Step 0 — Already connected?

Look at the tools you already have. AI Commander tools are named
`session_status`, `remote_exec`, `list_machines`, `remote_job_start` (and more
`remote_*`). The server may carry another name — a claude.ai connector the user
named "aic", Claude Code exposing the user's claude.ai connectors, or Grok
exposing Cursor's servers as `cursor__user-aicommander-*`.

If you have them: call `session_status` with the user's code (or alias) and stop
here. Do not add a duplicate server.

## Step 1 — Add the server (you can run shell commands)

**Claude Code**
```
claude mcp add --transport http aicommander https://aicommander.dev/mcp
```
Then ask the user to sign in — the command is interactive, so the user runs it:
`! claude mcp login aicommander` (or `/mcp` → `aicommander` → Authenticate).
Over SSH / headless: `! claude mcp login aicommander --no-browser` prints a URL;
the user opens it, signs in, and pastes the redirect URL back. New tools may only
appear after a reload or a new session.

**Codex CLI**
```
codex mcp add aicommander --url https://aicommander.dev/mcp
```
This itself opens the sign-in page. Do NOT also run `codex mcp login` (that
registers a second client). Use `codex mcp login aicommander` (add
`--no-browser` when headless) only to redo a failed or expired sign-in.

**Grok CLI**
```
grok mcp add --transport http aicommander https://aicommander.dev/mcp
```
Grok does not start the sign-in on its own and you cannot trigger it. Ask the
user: type `/mcps`, select `aicommander`, press `i`, finish sign-in in the browser.

**Other CLI / IDE clients** (Cursor, Gemini CLI, VS Code, Zed, …): use the
per-client section of https://aicommander.dev/llms-full.txt (section 4).

## Step 1b — You are a chat app (ChatGPT, claude.ai, Claude Desktop, mobile)

You cannot add a connector yourself. Give the user these steps:

- **ChatGPT (web):** Plugins → plus button → Add custom MCP server. Name it
  `aicommander`; Connection URL `https://aicommander.dev/mcp`; authentication
  OAuth. Tick "I understand and want to continue", create it as a plugin,
  install, then type `@` in a new chat. Running commands needs ChatGPT Business
  or Enterprise/Edu on the web (Pro is read/fetch only; no mobile).
- **claude.ai / Claude Desktop:** Settings → Customize → Connectors → Add custom connector →
  URL `https://aicommander.dev/mcp`, then Connect and sign in. Connectors added
  on claude.ai are also available in Claude Desktop and the mobile apps.

## Sign-in — what the user will see

The browser page asks for the user's email and sends a one-time **email code**
to type in (not a magic link). Accounts with a passkey can use the passkey
instead.

## Step 2 — Verify

Call `session_status` with the user's code (`AIC-…`) or saved alias and report
whether the machine is online or offline. If the user has not given you a
machine code, ask them for it — the AI Commander app shows it in the menu bar /
tray after install; on a headless Linux server it is printed by
`sudo aicommander-agent status --reveal`. If no agent runs on the machine yet,
the user installs one — on Linux:
`sudo npm i -g @aicommander/agent && sudo aicommander-agent install` (Node.js ≥20);
on macOS / Windows the desktop app; all options: https://aicommander.dev/howto/#install-agent

## Pitfalls

- **Signed in ≠ machine access.** A new account that first uses a code older
  than one hour gets a link that starts BLOCKED, pending the machine operator's
  approval. The operator unblocks it in the desktop app's "Linked Accounts"
  view, or on Linux with `aicommander-agent list-admins` then
  `aicommander-agent unblock-admin <n>`. Do not recommend resetting the code —
  that removes every linked account.
- **"ACCESS PAUSED — dashboard sign-in required".** The account's presence
  window lapsed (72h by default; the owner changes it to 24h / 48h / 7 days in
  the AI Commander dashboard → **Security** tab — changing it never requires
  reconnecting or re-authorizing). Ask the user to sign in at https://aicommander.dev/dashboard/ — that
  is all; the same connector then keeps working. Do NOT reconnect, re-authorize
  or re-log the connector. Running jobs keep running.
- **Session codes are credentials.** Never put a code in a link you share, a
  web page URL, analytics, logs, issue trackers or public examples; the REST
  fallback's own endpoints are the only exception. Never echo
  an API key back into chat.

## Fallback (only if MCP is not possible)

A plain REST API exposes the same operations — see section 4 → "REST API" in
https://aicommander.dev/llms-full.txt. Anonymous, code-only access (no sign-in)
works only during a code's first hour; after that, sign in or use an API key.