Harness SDK overview

The Harness SDK connects a custom agent runtime, called a harness, to BeeOS Cloud. It is published for TypeScript and Python, and both packages expose the same concepts under matching names.

To call Cloud from your product backend, use the Cloud SDK (SDK overview).

What it is for

• Register the runtime with Cloud, receive a short-lived lease, and renew it with signed heartbeats.
• Receive runtime method calls such as session/prompt as durable deliveries, acknowledge them, and append results.
• Stream chat replies into the reply message that Cloud pre-creates, read conversation history, and follow realtime events.
• Call Agent Gateway with signed requests: files, canvas tokens, agent-to-agent calls, channels, events, connectors and automations.
• Open the canvas relay and the terminal bridge, and verify the execution grants that arrive with runtime methods (TypeScript only).

Who it is for

Authors of a custom harness or agent runtime who own the model loop and the inbound transport, and want BeeOS to supply identity, messaging, files, canvas and agent-to-agent calls. It is not a client for product backends.

Supported languages

Language	Package	Version	Requires	Dependencies
TypeScript	@beeos-ai/cloud-harness-sdk	1.0.0	Node.js ≥ 22 (ESM)	centrifuge, ws, @beeos-ai/beeos-types
Python	beeos-cloud-harness-sdk	1.0.0	Python ≥ 3.11	httpx, cryptography; the package root uses only the standard library

Modules

One page per module. Every public class, function and method has its signature, a parameter table, the return type and a description. Shared types and enumerations are in the appendix.

Module	What it covers	Availability
Install and authenticate	Install, credentials and initialisation	TypeScript and Python
Registration and lease	Register a runtime, renew its lease with heartbeats, and persist its identity.	TypeScript and Python
Identity and request signing	Ed25519 key pairs, signed request headers, and canonical hashing.	TypeScript and Python
Receiving runtime methods	Read, renew and acknowledge deliveries, append results, and use the lease-authenticated HTTP plane.	TypeScript and Python
Chat replies and realtime	Send and stream chat replies, read history, and subscribe to realtime events.	TypeScript and Python
Python agent runtime	The stdlib-only BeeOSAgentRuntime facade of the Python package root.	Python only
Agent Gateway client	Signed requests to Agent Gateway: files, canvas tokens, agents, channels, A2A, events, connectors and automations.	TypeScript and Python
Canvas relay and terminal bridge	WebSocket helpers for the canvas relay and the terminal bridge.	TypeScript and Python
Execution grant verification	Verify the execution grants delivered with runtime methods against Cloud's published keys.	TypeScript only
Retry and HTTP errors	Backoff policies, transient-error classification and the Cloud HTTP error type.	TypeScript and Python
Operations and runtime methods	The operation route table and the runtime methods Cloud may deliver.	TypeScript and Python
Appendix: types and enumerations	All shared structures and enumerations with their fields and values	TypeScript and Python

Differences between the two languages

Capabilities that exist in one language only are marked on their page and listed here.

Module	TypeScript only	Python only
Registration and lease	InstanceAuthorityRuntimeRegistrationTransport, RuntimeRegistrationAuthoritySource, RuntimeTransportFailurePolicy, RuntimeRegistrationLeaseExpiredError	load_or_create_identity, save_identity, FENCED_RETRY, HEARTBEAT_TRANSPORT_FAILURE_THRESHOLD, IDENTITY_FILE_NAME, RUNTIME_CURRENT_MANIFEST_DIGEST, RUNTIME_RPC_CONTRACT_REVISION, RUNTIME_RPC_PROTOCOL_VERSION, RuntimeRegistrationError, RuntimeRegistrationIntentConflict
Identity and request signing	AgentRequestIdentity, agentIdentityFromKeyPair, agentRequestAuthHeaders, authenticatedAgentFetch	canonicalize_jcs, generate_agent_key_pair, runtime_domain_hash, sha256_hex, signing_path_from_url, AGENT_PROJECTION_HASH_DOMAIN, HEARTBEAT_HASH_DOMAIN, REGISTRATION_HASH_DOMAIN
Receiving runtime methods	RuntimeDeliveryAuthorityPort, RuntimeDeliveryOriginPort, RuntimeDeliveryPort	create_runtime_delivery_port
Chat replies and realtime	BoundRuntimeChatReply, CentrifugeClientLike, CentrifugeRealtimeFactory, RuntimeChatAuthorityPort, RuntimeChatClient, RuntimeChatHttpPort, RuntimeChatRealtimePort, RuntimeChatReplyStream, RuntimeRealtimeSubscription, bindExistingRuntimeChatReply, createCentrifugoRealtimePort, createRuntimeChatClient, createRuntimeChatHttpPort, normalizeMessage, subscribeRuntimeRealtime, RUNTIME_CHAT_PATHS, RuntimeChatPreparedClearError	—
Python agent runtime	—	BeeOSAgentRuntime, extract_chat_prompt, extract_session_prompt, BeeOSAgentError
Execution grant verification	CloudGatewayGrantJwksVerifier, CoreExecutionAuthorizationVerifier, GatewayGrantJwksVerifier, MessageServiceBoundaryJwksVerifier, RuntimeJwksVerifier, SplitIssuerRuntimeAuthorizationVerifier, createCloudGrantVerifier, warmGrantJwks	—
Retry and HTTP errors	abortableSleep	TRANSIENT_STATUSES
Operations and runtime methods	HarnessOperationId	CHAT_PROMPT_METHOD

Two differences affect how you write a harness. TypeScript has no registration identity store: you pass the registration id, journal store id and journal generation yourself, and the Python load_or_create_identity keeps them in a file. The Python package root also contains BeeOSAgentRuntime, a small facade that authenticates with one bearer token instead of the Ed25519 signature and the runtime lease.

How to read the reference

• Code blocks have a TypeScript tab and a Python tab. A section that exists in one language only says so under its title.
• Type names in tables link to the appendix, which lists every field and every enumeration value.
• Names are written in TypeScript spelling in field tables; the Python name is shown next to it when it differs.

Source and version

This reference describes @beeos-ai/cloud-harness-sdk@1.0.0 and beeos-cloud-harness-sdk==1.0.0. Source: beeos-ai/beeos-cloud-harness-sdk-node and beeos-ai/beeos-cloud-harness-sdk-python.