Docs
Sign in

Move an agent's work to another machine and/or switch its model.

One mechanism for a Mac to Boat handoff, a Boat to Mac handoff and a model, connection or harness switch.

POST/api/v1/agents/{id}/move

Scopecrews

The same agent continues; no second agent is created. A working agent keeps working while its work (uncommitted changes too) is copied onto the task branch; then its turn is stopped at a safe point, what it left is saved, and its next run continues from that commit and is told it is taking over. target defaults to {"kind": "stay"} (a switch only); connectionId, model and options default to the agent's own. A move to the cloud goes through the planner like a launch: it reserves budget, honours the crew's and the install's caps and the start gates, and may start a VM. Follow it with agent.move events or GET /agents/{id}/moves. When an API key calls it, the timeline records who did what and the outcome. No query parameters.

Path parameters.

idstringrequired

The agent's id.

Headers.

Idempotency-Keystring

Makes a retry safe: the same key with the same request returns the first answer and does nothing else.

Body.

targetobject

Where the work goes. Default: stay on the machine it is on (a model or harness switch). Default {"kind":"stay"}.

ShowHide 2 fields

kindenumrequired

stay on the machine it is on, cloud, or node with nodeId.

nodeIdstring

The machine to move to. At least 5 characters. With kind node.

connectionIdstring

Another model connection (its harness comes with it). Default: the agent's own. At least 5 characters.

modelstring

Model on that connection. Default: the agent's model when the connection is unchanged, else the connection's default. At least 1 character.

optionsobject

Per-run settings chosen alongside a model. Unset means the harness's own default.

ShowHide 1 field

effortenum

How much reasoning the model spends, where its harness lets you choose. Left out, the harness's default. One of low, medium, high, xhigh, max.

Response.

200 OK: a JSON object. The example has placeholder values.

409 conflict
Refused with 409 conflict and the reason, changing nothing, when the agent or the target cannot do it now (read GET /agents/{id}/move-options first).
422 validation_failed
The body does not match its schema; each problem is in details.