Harnesses

Overview

The harnesses domain manages the configured harnesses of an instance and lists the models they can run (UHP). Create and update are synchronous: the operation descriptions say Cloud submits every runtime operation and waits before it responds, so give these calls a client timeout of at least 60 seconds.

7 operations · SDK resource: TypeScript cloud.harnesses · Python cloud.harnesses · Go cloud.Harnesses · API overview

Operations whose path starts with /uhp/v1 are served from https://api.cloud.beeos.ai/uhp/v1 instead of https://api.cloud.beeos.ai/v1; the SDKs switch automatically.

Main objects

• UHPHarnessCreate: the configuration you send to create or update a harness.
• UHPHarness: a configured harness.
• UHPHarnessModels and UHPModelCatalog: the models of one harness and the model catalogue by backend.

UHPHarnessCreate

Every field, and the methods that use this object: appendix.

UHPHarness

Every field, and the methods that use this object: appendix.

UHPHarnessModels

Every field, and the methods that use this object: appendix.

UHPModelCatalog

Every field, and the methods that use this object: appendix.

UHPMcpServer

A remote MCP server attached to a harness. Only enabled entries are connected for a turn; a disabled entry must not be contacted at all. An unreachable server must not fail the task. Unchanged from 2026-08-11: a process (stdio) server is declared inside a plugin, see PluginMcpServer.

Every field, and the methods that use this object: appendix.

UHPSkill

A skill is a FOLDER, not a file. A server must materialise the whole folder where the agent can read it — materialising only SKILL.md breaks every skill carrying references, scripts or data. Round-tripping a harness through GET and PUT must not lose skill contents.

Every field, and the methods that use this object: appendix.

UHPPlugin

An Agent Plugins package installed into a harness: plugin.json at the root, MCP servers in mcp.json, skills under skills/. A client writes files (or passes back blob) and optionally name and enabled; the server derives manifest, mcpServers, skills and skipped from the package on every write and ignores those fields on input. A refused package leaves the harness unchanged.

Every field, and the methods that use this object: appendix.

UHPModel

Every field, and the methods that use this object: appendix.

Typical flow

1. Create a harness with harnesses.create, then read it with harnesses.get or list all with harnesses.list.
2. Change its configuration with harnesses.update.
3. See which models it can run with harnesses.listModels; harnesses.listAllModels gives the catalogue by backend.
4. Run work on the harness with responses. harnesses.delete is not supported yet and returns 422.

See Manage harnesses for the update rules and error handling.

Methods

harnesses.list

GET /uhp/v1/harnesses · Operation ID listHarnesses

List configured harnesses

SDK methods

Response

200 Harnesses within the caller's scope. May be empty. · application/json

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.list();
console.log(result);

harnesses.create

POST /uhp/v1/harnesses · Operation ID createHarness

Create a configured harness

Synchronous: Cloud submits every runtime operation and waits (up to 45s, so use a client timeout of at least 60s) before responding. 502 harness_error lists per-item results in error.detail.operations[]; 504 beeos_harness_update_in_progress means work continues, retry the identical request after Retry-After (a create without an Idempotency-Key is not re-attached and would create a second harness); 409 beeos_harness_busy means a different write is in flight, retry after Retry-After; 409 beeos_idempotency_conflict means the Idempotency-Key was used with a different request; 503 harness_unavailable means the instance is not running or the operation journal is unavailable; 413 means the body exceeds 4 MiB (upload large skills as a Files blob). The optional Idempotency-Key header (1-128 visible ASCII characters) makes a create (POST, or PUT with template_id) safe to resend: the same key and request returns the same harness. instance_id and name are required and base must equal the instance runtime (422); template_id and template_version create the harness from an agent template; default_model is honored only here. a non-empty skills or mcp_servers is rejected on create (422 beeos_field_not_supported); add them with PUT. Not supported by BeeOS Cloud yet (422 beeos_field_not_supported): a non-empty system_prompt, disabled_tools, environment or plugins, or any max_step or timeout_seconds. An unchanged name and empty values are accepted, so a GET-modify-PUT round trip works.

SDK methods

Parameters

Request body

application/json · required · Schema: UHPHarnessCreate

Response

200 The created harness · application/json · Schema: UHPHarness

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.create({ base: "example_base" });
console.log(result);

harnesses.get

GET /uhp/v1/harnesses/{harness_id} · Operation ID getHarness

Get one harness

SDK methods

Parameters

Response

200 The harness · application/json · Schema: UHPHarness

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.get("harness_123");
console.log(result);

harnesses.update

PUT /uhp/v1/harnesses/{harness_id} · Operation ID updateHarness

Update a harness configuration

Synchronous: Cloud submits every runtime operation and waits (up to 45s, so use a client timeout of at least 60s) before responding. 502 harness_error lists per-item results in error.detail.operations[]; 504 beeos_harness_update_in_progress means work continues, retry the identical request after Retry-After (a create without an Idempotency-Key is not re-attached and would create a second harness); 409 beeos_harness_busy means a different write is in flight, retry after Retry-After; 409 beeos_idempotency_conflict means the Idempotency-Key was used with a different request; 503 harness_unavailable means the instance is not running or the operation journal is unavailable; 413 means the body exceeds 4 MiB (upload large skills as a Files blob). The optional Idempotency-Key header (1-128 visible ASCII characters) makes a create (POST, or PUT with template_id) safe to resend: the same key and request returns the same harness. An absent field is unchanged; a present list replaces the whole list. When skills is present it is diffed against the installed skills: listed skills with files, content or blob (exactly one) are installed; an installed skill listed with a different enabled flag is updated; installed skills that are omitted are uninstalled unless bundled with the runtime; a listed skill that is not installed and has no files, content or blob returns 422; enabled:false on a fresh install returns 422. When mcp_servers is present it is diffed against the runtime MCP servers: a server sent with a credential (headers or auth plus expires_at, at most 24 hours ahead) is set, a connected server sent without one is kept, omitted servers are unset; the url must be https and transport is http or sse; GET never returns a url or credential. 422 beeos_mcp_not_supported is returned only when the instance runtime has no MCP methods. base is immutable; a name change or a default_model different from the current one (without template_id) returns 422 beeos_field_not_supported. Not supported by BeeOS Cloud yet (422 beeos_field_not_supported): a non-empty system_prompt, disabled_tools, environment or plugins, or any max_step or timeout_seconds. An unchanged name and empty values are accepted, so a GET-modify-PUT round trip works.

SDK methods

Parameters

Request body

application/json · required · Schema: UHPHarnessCreate

Response

200 The updated harness · application/json · Schema: UHPHarness

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.update("harness_123", { base: "example_base" });
console.log(result);

harnesses.delete

DELETE /uhp/v1/harnesses/{harness_id} · Operation ID deleteHarness

Delete a harness

Not supported by BeeOS Cloud yet: returns 422 beeos_harness_delete_not_supported once the harness is found.

SDK methods

Parameters

Response

200 Deleted · application/json

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.delete("harness_123");
console.log(result);

harnesses.listModels

GET /uhp/v1/harnesses/{harness_id}/models · Operation ID listHarnessModels

Models this harness can run

SDK methods

Parameters

Response

200 The harness's allowed models, default and authorized fallback · application/json · Schema: UHPHarnessModels

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.listModels("harness_123");
console.log(result);

harnesses.listAllModels

GET /uhp/v1/models · Operation ID listModels

The model catalogue, by backend

SDK methods

Response

200 Models grouped by backend, each with computed availability · application/json · Schema: UHPModelCatalog

Errors

The error schemas are described in Errors.

Example

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.harnesses.listAllModels();
console.log(result);