Agents & Machines
runAgent
Run Agent
Start (spawn) an autonomous agent on one of your machines to carry out a task.
Ask Claude, ChatGPT, Cursor or any AI connected to The Cloud "run an agent", and it calls runAgent.
Example call
The MCP tools/call params, with the required arguments only.
{
"arguments": {
"prompt": "<prompt>"
},
"name": "runAgent"
}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 to use the one machine that is active and online; the refusal when none or several qualify names the candidates.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.
Questions
What does runAgent do?
Start (spawn) an autonomous agent on one of your machines to carry out a task. It is one of the tools The Cloud MCP server gives every connected AI.
How do I use runAgent from Claude or ChatGPT?
Connect your AI to The Cloud at https://mcp.thecloud.so/mcp and sign in once. Then ask Claude, ChatGPT, Cursor or any AI connected to The Cloud "run an agent", and it calls runAgent.
Is runAgent safe to let an AI call?
runAgent changes your workspace. What an AI creates is Private until you share it. It reaches a system outside The Cloud on your behalf.
Connect
One endpoint gives your AI this tool and every other one: connect Claude, ChatGPT, Cursor or Gemini, read what The Cloud is, or see pricing.