Cloud quickstart

Use the Server SDK from trusted backend code. Use Server SDK 2.0.0. Set BEEOS_CLOUD_API_URL to https://api.cloud.beeos.ai/v1 (or your environment’s /v1 URL), a bsk_ server key in BEEOS_API_KEY, and an app-local BEEOS_EXTERNAL_USER_ID mapped from the authenticated product user. TypeScript and Python expose BeeOSClient with typed resource methods and results.

Create a managed instance

Select a published variant_id from GET /v1/instance-templates and put it in BEEOS_VARIANT_ID. For OpenClaw or Hermes, supply BYOK llm.providers and llm.models: each model references a provider ID, with exactly one default at order 0. The provider protocol is openai or anthropic; use its matching base URL and your own provider key. This example uses the OpenAI protocol.

AgentBay and BeeOS browser/mobile variants run without a Cloud-injected model: omit the entire llm block for those model-free frameworks. Do not send retired model_primary or model_credential fields. Keep provider keys in backend configuration; never log BYOK request bodies.

Python: pip install beeos-cloud-sdk==2.0.0.

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

const cloud = new BeeOSClient({
  baseURL: process.env.BEEOS_CLOUD_API_URL!, // https://api.cloud.beeos.ai/v1
  apiKey: process.env.BEEOS_API_KEY!, // bsk_…, backend only
}).withExternalUser(process.env.BEEOS_EXTERNAL_USER_ID!);

const created = await cloud.instances.create({
  name: "assistant-prod",
  variant_id: process.env.BEEOS_VARIANT_ID!,
  llm: {
    providers: [{
      id: "my-provider",
      protocol: "openai",
      base_url: process.env.BEEOS_MODEL_PROVIDER_URL!,
      api_key: process.env.BEEOS_MODEL_PROVIDER_API_KEY!,
    }],
    models: [{
      provider_id: "my-provider",
      model: process.env.BEEOS_MODEL_ID!,
      role: "default",
      order: 0,
    }],
  },
}, crypto.randomUUID());
console.log(created.data.id);

Send work after readiness

Creation returns 202 with data.id and an operation; it does not mean the instance is ready. Use cloud.instances.getStatus(created.data.id) (Python: cloud.instances.get_status(created["data"]["id"])) until it is running, then use cloud.harnesses.list() to select its ready harness. The SDK sends the external-user header and uses /uhp/v1/harnesses. Set BEEOS_HARNESS_ID to that harness ID; it is distinct from the instance ID. Surface provisioning and readiness failures to your product backend.

The following code continues with the scoped cloud client from above:

const response = await cloud.responses.create({
  input: "Hello",
  metadata: { harness_id: process.env.BEEOS_HARNESS_ID! },
}, crypto.randomUUID());
console.log(response.id, response.status, response.output);

A Response has its own ID, status, and output. For another turn, pass previous_response_id; for background work, set background: true and retrieve progress with cloud.responses.get(response.id) (Python: cloud.responses.get(response["id"])). The Harness SDK handles work inside the running process.

Return product-visible results through your backend and its authenticated user channel. The frontend never receives the server key or provider keys; see product frontend integration.