# CommandAGI, for agents

<!-- Written by scripts/sites/front-door.mjs from sites/pages/docs/getting-started/en.md, sites/pages/docs/sdk/en.md, sites/pages/docs/agents/en.md, deployments/clients/host/package.json and global/worlds/eval-reach/world.tsx. Do not edit: edit those. -->

> We make the world commandable. Command things into existence, swarms of agents and fleets of computers, from one prompt, every command on the record.

This page is for an AI agent that a person sent here (https://commandagi.com/agents.md). It says what CommandAGI is, how to connect to it over MCP or its command line, the first world to write, and the rule for acting on real machines. The docs are at https://commandagi.com/docs; a short index for models is at https://commandagi.com/llms.txt.

## What CommandAGI is

CommandAGI is a workbench where people and agents plan, simulate and run real machines. Everything in it rests on four ideas:

- **Devices.** A device definition describes one kind of machine as a set of **channels** — a G-code line, a servo bus, a video stream, a shell. A CNC mill, a laser, a printer, an arm, a drone, a phone, a camera and a computer are all devices.
- **Worlds.** A world places devices as **units**, with positions, in a space. A world is either `physical` (it reaches hardware) or `simulation` (every channel runs in a simulator).
- **Runs.** What devices do is recorded as **streams** in a run: one folder per run, one stream per unit's channel, all on one clock.
- **Grants.** An agent or a person acts on physical hardware only inside a **standing grant** an account gave it.

All of it is plain files in a folder you choose.

## Connect over MCP

### The hosted server

`https://api.commandagi.com/mcp` — Streamable HTTP, stateless, JSON responses. Authenticate with an API key (`cagi_…`), created in the workbench from the account menu's **API keys**.

```sh
claude mcp add --transport http commandagi https://api.commandagi.com/mcp \
  --header "Authorization: Bearer cagi_YOUR_KEY"
```

### The local relay, for machines on your person's computer

On a computer running the host, `commandagi mcp` is a stdio MCP server that relays to the host's own endpoint. Give it the agent's host credential — in the environment or a file, never as an argument:

```sh
claude mcp add commandagi -e COMMANDAGI_CREDENTIAL=cagp_… -- commandagi mcp
# or
claude mcp add commandagi -- commandagi mcp \
  --credential-file ~/.config/claude/commandagi.credential
```

## Install the command line

The `commandagi` command and this computer's host are one npm package, `@commandagi/host`. It is the CommandAGI local host and the commandagi command: the workbench, the files and devices of this computer, the MCP host, the 3D design service and the link to your account.

```sh
npm install -g @commandagi/host
commandagi whoami
```

## Write your first world

A world is code: one `world.tsx` that declares a `<world>`, the same file the workbench's editors write back to. This is `cloud://global/worlds/eval-reach/world.tsx`, a simulation the engine steps as it is. Open it: https://commandagi.com/?open=%2Ffile%3Fpath%3Dworlds%2Feval-reach%2Fworld.tsx%26drive%3Dcloud%3A%2F%2Fglobal

```tsx
// eval-reach: a world in code. The world editor writes each edit to this file; edit it here as well.
export default () => (
  <world
    name="Eval: reach"
    kind="simulation"
    description="The reach grading fixture: an SO-101 arm on a bench and a target marker its tool point must come within 2 cm of."
  >
    <scene
      hz={240}
      record_hz={30}
      robots={[{ id: "arm", device: "../../devices/so101-follower-arm/definition.tsx", at: [0, -0.049, 0.76], joints: { shoulder_pan: 0, shoulder_lift: 0.5399612373357457, elbow_flex: 0, wrist_flex: 0, wrist_roll: 0, gripper: 1.745329 } }]}
    >
      <body
        id="ground"
        shape={{ type: "box", hx: 3, hy: 3, hz: 0.1 }}
        at={[0, 0, -0.1]}
        type="fixed"
        friction={0.8}
        color={[0.32, 0.36, 0.34]}
      />
      <body
        id="bench"
        shape={{ type: "box", hx: 0.6, hy: 0.4, hz: 0.02 }}
        at={[0, 0, 0.74]}
        type="fixed"
        friction={0.7}
        color={[0.55, 0.45, 0.35]}
      />
      <body
        id="target"
        shape={{ type: "sphere", r: 0.01 }}
        at={[0.08, -0.12, 0.86]}
        type="fixed"
        sensor={true}
        color={[0.9, 0.2, 0.2]}
      />
    </scene>
  </world>
);
```

## The grant rule

A **standing grant** is authority given to one principal by an explicit act of a principal of the account: a person, or an agent. People are not privileged over agents: the same identity, scope and role checks apply to both. An agent may grant itself what its work needs with the MCP tool `grant`, and the grant records the agent as `grantedBy`, so you see who granted what and can revoke it.

**Safing is always allowed.** `stop`, `disarm` and `close` — and safing commands such as feed hold, pause, emergency stop and torque off — are allowed to anyone holding any unexpired grant on the unit, to whoever opened the session, and to the account's own person. Cancelling a resting order is safing too.

Grants apply to **physical** worlds. A simulation world needs none.

Every action follows these rules:

- **Recorded before it is sent.** Before the driver is called, a note — the principal and the action — is appended to the run's stream and flushed. A read-only project refuses the action rather than act without a record.
- **An acknowledgement is not a state.** A reply or `ok` never implies the commanded state was reached. Commands stay pending until the machine reports a state.
- **Unknown stays unknown.** A lost link is recorded as `state: unknown`. A stream that ended without an end record reads *interrupted: state unknown*.
- **No silent retries.** A physical command is never retried by the system. An agent may decide to try again; that decision is its own recorded command.
- **Bounds are the driver's job.** Declared limits, intervals and allowed verbs are enforced by the driver, not by a person. Input streams are paced: one action at a time, at least 30 ms apart.
- **Simulated and physical never mix.** A run belongs to one world, and its records' source must match the world's kind.

## Read next

- [Getting started](https://commandagi.com/docs/getting-started): Open the workbench, open a world, learn devices, worlds and runs, and run your first simulation.
- [Connecting a machine](https://commandagi.com/docs/connect): The host on your computer, linking it to your account, pairing hosts with each other, page drivers, and the full driver catalog with what each has been verified against.
- [Agents and standing grants](https://commandagi.com/docs/agents): Principals and credentials, standing grants, arming, safing verbs, and the rules every action follows — recorded before it is sent, unknown kept unknown, never silently retried.
- [SDK and MCP](https://commandagi.com/docs/sdk): Connect Claude Code, Codex or any MCP client to CommandAGI — the hosted server, the local relay and their tools — and drive it from code with the TypeScript and Python SDKs.
- [File formats](https://commandagi.com/docs/formats): Every CommandAGI file, one by one — device definitions, worlds, runs and streams, documents, circuits, simulations, dashboards and settings. Plain files, nothing hidden.
- [API reference](https://commandagi.com/docs/api): Base URLs, API keys and authentication, saving files safely, the main endpoint groups, and model ids.