Agents & Machines
runAgent
Run Agent
Start (spawn) an autonomous agent on one of your machines to carry out a task.
Arguments
chipsstring[]optionalActivity chips to tag the session with at spawn: what it is DOING, from the project's chip set (defaults: repair, fix, build, review, research, merge-conflict, docs, deploy). These are session tags with a display identity, so the Agents…machineIdstringoptionalWhich machine to run on (machineId from listMachines). Omit only when exactly one machine is active.modelstringoptionalOptional model id. OMIT IT and the fleet picks the seat for you: the medley law rotates Claude → Codex → Grok(Cursor) across the seats that machine reports ready with a current smoke proof, one turn per spawn, so lanes spread across the…nativebooleanoptionalRun on the machine's own local model via the on-box native provider instead of a metered cloud model: free, with no session-limit ceiling. Defaults to Alpaca (gpt-oss:20b); pass model for Mule (qwen3-coder:480b). Requires the box to have…projectIdstringoptionalDispatch the agent into a Cloud Project (its projectId). The run inherits the project's Space scope, so teammates in a Space the project is shared with see its activity in the Agents view. You must be a member of the project's Space. Omit…promptstringrequiredThe task for the agent: its opening instruction. Be specific and self-contained; this is the first thing the agent acts on.repoobjectoptionalBind the agent to a GitHub repo (the Dev Loop): the machine clones it, the agent works on a branch, and its changes are committed and opened as a pull request to baseBranch. Pass headBranch to continue an existing branch/PR instead of a…strictSeatbooleanoptionalRefuse the spawn outright if the seat named in `model` cannot run on that machine, instead of falling back. By default a named seat that is unavailable at dispatch (no smoke proof, out of credits, not installed, not signed in) does NOT…studioAppobjectoptionalBind the agent to a Studio app you administer (the Studio Dev-Loop): the machine materializes the app's file tree into the workspace, the agent edits locally, and changes push back through the Studio write tools: building your Cloud apps…taskIdstringoptionalFile this lane against a Task you ALREADY have (its taskId from listTasks, readTask or readLedger) instead of opening a new ledger row for it. Use it when the ask is already written down, such as a backlog item you are now dispatching, so…titlestringoptionalOptional short title for the agent chat. Defaults to a line drawn from the prompt.
Returns
The registry does not declare a return shape.
Ask for it
The Cloud routes these requests to this verb.
- run an agent
- spawn an agent to…
- have an agent do…
- kick off an agent
Pair it with
The verbs that finish the job.