Cloud Agent Lifecycle

Create an agent

POST /v2/agents requires model_provider. The other fields are optional:

Field	Behavior
name	Defaults to Cloud Agent. Names are trimmed and must contain 1–255 bytes.
system_prompt	Instructions added to the harness configuration. The public schema limits this to 65,536 characters.
initial_message	Starts the first run after setup; omitted or whitespace-only messages do not start one. The schema limits it to 65,536 characters.
runtime	Defaults to {"type":"fresh"}. Select fresh, checkpoint, or existing as below.
repositories	Ordered connected GitHub repository selections for fresh/checkpoint runtimes.
harness	Optional id and kind for an additional instance on an existing runtime. Fresh/checkpoint creation uses the default harness.

Creation returns 201 before fresh-runtime initialization finishes. Use initial_message when the first task must wait for platform setup and repository checkout. Poll the agent and run list instead of repeatedly creating agents.

Start a fresh computer

{
  "name": "Research assistant",
  "model_provider": {"type": "managed", "id": "your-provider-id"},
  "runtime": {"type": "fresh"},
  "initial_message": "Inspect your environment and report what tools are available."
}

Fresh creation defaults to the cloud_agent image. The optional image_id selects an image, but Cloud Agent operations require a compatible Cloud Agent bundle; an arbitrary runtime image is not a substitute. Do not include id or checkpoint_id in a fresh-runtime reference.

Initialize GitHub repositories

Connect GitHub and grant access to the desired repositories first. Discover repository IDs through List connected repositories.

{
  "name": "Repository assistant",
  "model_provider": {"type": "managed", "id": "your-provider-id"},
  "runtime": {"type": "fresh"},
  "repositories": [
    {"repository_id": 123456, "branch": "main"},
    {"repository_id": 789012}
  ],
  "initial_message": "Read the repository instructions and summarize the project."
}

The first repository becomes Pi’s working directory. Omit branch to select the repository’s default branch. All selections must be accessible to the API key. The initial message waits for checkout. This requires a runtime bundle with repository workspace support.

Restore a checkpoint

Use a checkpoint of a compatible Cloud Agent runtime:

{
  "name": "Restored assistant",
  "model_provider": {"type": "managed", "id": "your-provider-id"},
  "runtime": {
    "type": "checkpoint",
    "checkpoint_id": "your-checkpoint-id"
  },
  "initial_message": "Inspect the restored workspace before continuing."
}

checkpoint_id is required and cannot be empty. Do not include id or image_id. Repository selections are supported using runtime restore checkout rules. See Checkpoints for capture and restore.

Share an existing computer

{
  "name": "Reviewer",
  "model_provider": {"type": "managed", "id": "same-provider-id"},
  "runtime": {"type": "existing", "id": "existing-runtime-uuid"},
  "harness": {"id": "reviewer", "kind": "cloud_agent"},
  "initial_message": "Review the work in this computer's workspace."
}

Supply the runtime_id, not a composite agent ID. The runtime must have Cloud Agent support and the same provider configuration and credential. Nonempty repositories are rejected because this mode reuses the workspace. Do not include checkpoint_id or image_id.

Omit harness.id to generate one. Explicit IDs use ASCII letters, digits, underscores, or hyphens and are 1–160 characters long. A new harness has an independent conversation but shares files, desktop, and model routing. kind is metadata; the implementation still uses Pi.

Identify, list, and rename

Treat the returned id as opaque. A default harness currently uses its runtime UUID as the agent ID. Additional harnesses use <runtime_uuid>--<harness_id>. Use runtime_id for runtime APIs and id for agent APIs.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  "$RUNTA_API_URL/v2/agents?limit=100&include_latest_reply=true" | jq .

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  "$RUNTA_API_URL/v2/agents/$AGENT_ID" | jq .

curl --fail-with-body --silent --show-error -X PATCH \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Renamed assistant"}' \
  "$RUNTA_API_URL/v2/agents/$AGENT_ID" | jq .

Listing returns {agents, next_cursor}. Pass a non-null next_cursor back as the URL-encoded after parameter. The public contract allows limit from 1 to 100; pagination is over backing runtimes, so a page can include additional harnesses from those runtimes. Additional harnesses are discovered while their runtime is running. Keep saved agent IDs when a runtime is stopped.

include_latest_reply defaults to false. When enabled, running agents may include latest_reply with run_id, text, created_at, and updated_at. This is a convenience preview, not a replacement for run history.

Only the name can be changed with the agent PATCH endpoint. status reflects runtime state, and the Unix-second timestamps come from the runtime. For pause, resume, and other computer lifecycle operations, use the runtime APIs with runtime_id.

Delete an agent or its computer

Request	Effect	Response
Delete the default harness	Requests deletion of the entire runtime, including other harnesses.	202
Delete an additional harness without delete_runtime=true	Deletes that harness; the computer remains. An active run can cause a conflict.	204
Delete any agent with delete_runtime=true	Requests deletion of the entire runtime.	202

The default value of delete_runtime is false, but it does not preserve the computer when deleting the default harness.

curl --fail-with-body --silent --show-error -X DELETE \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  "$RUNTA_API_URL/v2/agents/$AGENT_ID?delete_runtime=true"

Export needed files first. A 202 acknowledges asynchronous deletion. Poll the saved runtime UUID until GET /v2/runtimes/{runtime_id} returns 404 to confirm control-plane removal. Authorization errors or timeouts do not confirm deletion, and control-plane absence does not confirm completion of worker-local disk cleanup.