GRID Docs | General Robotics

The GRID agent reads documentation, writes Python skills and runs approved code through your robot’s GRID development session. You review the proposed action before it runs. A saved script, a finished process and a verified task are three different results.

Start a conversation

Set ANTHROPIC_API_KEY in the shell that starts GRID and sign in to GRID as usual. Inside the GRID terminal, run:

agent --robot <robot-name> help me write and test a task

Use agent --no-robot to write code without connecting to hardware. Running agent without either option reuses your current live robot connection. If there is no live connection, it offers an online-robot picker. Use --no-robot when you want to author code without attaching to that connection. Recent tool calls stay visible while the agent works. Press Tab for the full trace, and use arrow keys or Page Up / Page Down to scroll. Saved filenames are terminal hyperlinks. Escape cancels and closes the conversation after cleanup. Conversation history is retained between turns, but cannot be resumed after a CLI restart.

Review, run and check

The agent reads the docs, then saves a draft in your skill library, ~/.grid/skills/, the same wherever you start GRID. Draft saved means the code has not run. The agent can also revise an existing skill after reading it; if someone changed the file meanwhile, GRID refuses the save.
Before an action, review its target, source, arguments, limits and success condition. Press y then Enter to approve, or Enter / n to deny. Changes to the approved program or inputs require another approval. Read-only tools do not need approval.
GRID runs approved Python through the same runner as skill run, captures its output and reports the process result. After a completed run, an unchanged program may retry within its approved trial limit. A run that fails, times out or is cancelled needs a new approval.
After the process ends, GRID asks you to check the robot, stop it if needed, and confirm it has stopped. It then asks whether the approved task succeeded, failed, or remains unclear. An exit code or the model’s answer does not prove task success.

The person testing remains responsible for the prepared robot and its motion limits. Python runs with your host’s permissions; this is process supervision, not an OS sandbox. Connecting establishes a GRID session; it does not check physical readiness. V0 does not automatically inspect the robot or send a hardware stop. Cancellation ends the task process. You remain responsible for stopping the hardware, and GRID blocks another agent run until you confirm it stopped.

Call the agent without the terminal UI

Create a request file. query and all four limits fields are required; omit robot to work without a selected robot.

{
  "robot": "lab-robot",
  "query": "Inspect the setup and write a task. Try at most twice.",
  "limits": {
    "maxActions": 60,
    "maxSeconds": 900,
    "maxCostUsd": 3,
    "maxTrials": 2
  },
  "approvalDirectory": "/private/grid-approvals",
  "approvalTimeoutSeconds": 600,
  "answers": []
}

grid --json --exec "agent --request /absolute/path/request.json"

The final JSON result goes to stdout. Live approval notices go to stderr as JSON lines, so your application can watch for decisions while keeping stdout parsable as one document. Omitting approvalDirectory denies actions, but still permits read-only work and authoring. For each approval, the notice gives proposalPath, decisionPath, approvalHash, requestId and decideBy. Your application or an operator must:

Read the complete proposal and decide whether to allow it.
Write this decision to a temporary file beside decisionPath.
Atomically rename that file to the exact decisionPath from the notice.

{"approvalHash": "<hash from this proposal>", "approved": true}

Use false to deny. Every request has new paths, including retries. An expired, used or mismatched decision cannot approve a later request. The directory must belong to the current user and must not be writable by other users. The default wait is 600 seconds; approvalTimeoutSeconds accepts 60–3600 seconds. File approvals are unavailable on Windows; program execution requires POSIX process groups. answers supplies replies to the agent’s ordinary questions. It cannot approve execution or confirm a task outcome or a stopped robot. V0 headless runs can execute approved Python and return logs, but physical outcomes stay unknown. Without live operator confirmation, another run stays blocked until someone checks the robot and reconciles stopping in an interactive session. The final result’s data.host reports denials, action failures, cancellation, stop confirmation and task verification. Check the overall ok and code as well as the model’s text. needs_attention means a host check prevented success; invalid_request means the input was rejected, and setup_failed includes a missing model key. A model failure may supply its own error code.

Limits and recovery

Interactive defaults are 60 tool calls, 900 seconds of working time, 10 Python starts and a $3 model budget. Waiting for a person is excluded from working time. A trial counts a Python start, not each robot movement inside the program. Headless requests supply these limits explicitly. Session evidence is saved in ~/.grid/agent/sessions/<id>/events.jsonl. Keep any unresolved stop record: deleting it bypasses the block without establishing that the robot stopped. Check the robot and follow GRID’s recovery message in an interactive session. Recovery also checks that the old process has ended; it does not pre-approve another task. Documentation comes from the hosted GRID docs MCP. GRID_DOCS_MCP_URL overrides that endpoint for a custom deployment. See the CLI reference for the other GRID commands.

​Start a conversation

​Review, run and check

​Call the agent without the terminal UI

​Limits and recovery

Start a conversation

Review, run and check

Call the agent without the terminal UI

Limits and recovery