Harness management

The Cloud SDK manages the agents inside an instance only through UHP harnesses. The harnesses resource sends these calls to /uhp/v1 on the configured Cloud host. There is no generic runtime-method call.

TypeScript method	HTTP route	Purpose
harnesses.create(input)	POST /uhp/v1/harnesses	Create an agent; BeeOS extension instance_id and name are required
harnesses.update(id, input)	PUT /uhp/v1/harnesses/{harness_id}	Change skills or apply a template
harnesses.get(id) / list()	GET /uhp/v1/harnesses[/{harness_id}]	Read the current configuration
harnesses.listModels(id)	GET /uhp/v1/harnesses/{harness_id}/models	Models the harness can use

Python uses the same names in snake case (list_models); Go uses Create, Update, Get, List, and ListModels with UHPHarnessCreate. The discovery capability harness_management is still false; these calls work as described here regardless.

const harness = await cloud.harnesses.create({
  base: 'openclaw', name: 'support', instance_id: instanceId,
  default_model: 'openai/gpt-4.1',
});
await cloud.harnesses.update(harness.id, {
  base: 'openclaw',
  template_id: templateId,
  skills: [{ name: 'triage', blob: 'file_abc', sha256: bundleSha256, size_bytes: '18342' }],
});

Configuration

• Create: instance_id and name are required, and base must be the instance's runtime. default_model is honored only on create. Skills are rejected on create; add them with update.
• Update rules: an absent field is unchanged, and base is immutable. When skills is present it is compared with the installed skills:
  • a listed skill with files[] (inline files, within the 4 MiB request body), content, or blob (a Cloud Files file_... id with sha256 and size_bytes) is installed;
  • an omitted skill that was installed from the catalog is uninstalled;
  • a listed skill that is not installed and has no files, content, or blob returns 422;
  • enabled: false on a skill that is being installed returns 422; install it enabled, then disable it.
• Templates: the BeeOS extension template_id applies an agent template.
• Models: to pick a model for one turn, pass the Responses model field.

Not supported by BeeOS Cloud yet (all return 422):

Request	Code
harnesses.delete(id)	beeos_harness_delete_not_supported
non-empty mcp_servers	beeos_mcp_not_supported
default_model different from the current one on update (without template_id)	beeos_field_not_supported
name change, system_prompt, disabled_tools, environment, max_step, timeout_seconds, plugins	beeos_field_not_supported

Synchronous writes

create and update are synchronous. The descriptions of these operations in the OpenAPI document say that Cloud submits the runtime work and waits up to 45 seconds before it responds, so give these calls an HTTP timeout of at least 60 seconds.

Status	Meaning	What to do
200	Every change is applied	Use the returned harness
422	Validation failed or the request is unsupported; nothing was submitted	Fix the request
409 beeos_harness_busy	A different write to this harness is in flight	Retry after Retry-After
502 harness_error	Some items failed; error.detail.operations[] lists each item's kind, name, and status	Succeeded items are applied; resend the corrected request to retry the rest
503 harness_unavailable	The instance is not running or the operation journal is unavailable	Retry later
504 beeos_harness_update_in_progress	The work is still running	Wait for Retry-After, then resend the identical request

Resending the identical request after a 504 re-attaches to the in-flight work instead of starting it again. There is no ETag / If-Match support and no skill files endpoint.

See the harnesses domain for every operation and its fields.