@elizaos/plugin-elizacloud

Eliza Cloud plugin for elizaOS agents. The TypeScript package is backed by @elizaos/cloud-sdk, so runtime Cloud API calls, auth helpers, route wrappers, TTS, STT, image generation, containers, and gateway relay code use the same SDK surface as other Eliza Cloud clients.

Installation

npm install @elizaos/plugin-elizacloud
# or
bun add @elizaos/plugin-elizacloud

Register the plugin with your agent runtime:

import { elizaOSCloudPlugin } from "@elizaos/plugin-elizacloud";

const agent = new Agent({
  plugins: [elizaOSCloudPlugin],
});

SDK Contract

The TypeScript package has a hard dependency on @elizaos/cloud-sdk. Development checkouts resolve it with workspace:*; published packages are expected to consume the npm-published SDK version.

Runtime code must not build direct Eliza Cloud HTTP calls by hand. Use the SDK helpers in typescript/utils/sdk-client.ts:

ELIZAOS_CLOUD_BASE_URL remains the API base URL and defaults to https://www.elizacloud.ai/api/v1. createElizaCloudClient derives the site root from that API URL when generated SDK route wrappers need /api/v1/... paths.

typescript/providers/openai.ts is the one intentional transport adapter that passes the configured base URL to the Vercel AI SDK's OpenAI-compatible client. It is not a hand-rolled Cloud API fetch path.

Runtime Coverage

The only remaining runtime-adjacent fetch() usage is in the plugin test block for downloading a public audio fixture. It is not an Eliza Cloud API call.

Payments And Monetization

The plugin exposes one local route family for Cloud money flows: /api/cloud/billing/*. It forwards to the authenticated Cloud API using the same Cloud key as the rest of the plugin, so app UIs and agents do not need to handle Cloud credentials directly.

Supported local aliases:

Agent-initiated charges should use app charge requests for Stripe/OxaPay credit checkout or x402 payment requests for direct crypto settlement. Both request types accept callback channel metadata, so successful or failed payment events can be written back into the room where the charge was initiated.

Configuration

Get an API key from https://www.elizacloud.ai/dashboard/api-keys.

Browser builds must not receive secrets directly. Use ELIZAOS_CLOUD_BROWSER_BASE_URL and ELIZAOS_CLOUD_BROWSER_EMBEDDING_URL for browser-only proxy endpoints.

Usage Examples

import { ModelType } from "@elizaos/core";

const text = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Summarize the current agent state.",
});

// Structured output: route through TEXT_* with `responseSchema` (native tool calling).
const structured = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Return a JSON user profile with name and role.",
  responseSchema: {
    type: "object",
    properties: { name: { type: "string" }, role: { type: "string" } },
    required: ["name", "role"],
  },
});

const embedding = await runtime.useModel(ModelType.TEXT_EMBEDDING, {
  text: "Hello, world!",
});

const speech = await runtime.useModel(ModelType.TEXT_TO_SPEECH, {
  text: "Cloud text to speech is active.",
});

Adding Cloud Calls

1. Prefer an existing high-level SDK method when one exists.
2. Otherwise use a generated createElizaCloudClient(runtime).routes.* wrapper.
3. Use createCloudApiClient(runtime) for raw API-base endpoints that do not yet have a generated wrapper.
4. Keep all Eliza Cloud API auth/header/base-URL behavior inside the SDK helper layer.
5. Do not add direct fetch() calls for Eliza Cloud API routes in runtime code.

When the Cloud API adds or changes public routes, update the SDK first:

cd ../../packages/cloud-sdk
bun run generate:routes
bun run check:routes
bun run test:e2e

Then update this plugin to consume the new SDK route or helper.

Development

From the TypeScript package:

cd typescript
bun run typecheck
bun run test
bun run build
npm pack --dry-run

From the SDK package:

cd ../../packages/cloud-sdk
bun run check:routes
bun run test:e2e

bun run test:e2e in the SDK runs public real API checks by default and skips credentialed or destructive cases unless the required credentials and opt-in environment flags are present.

Publishing

The TypeScript package is published to npm as @elizaos/plugin-elizacloud. Publishing must include a compatible @elizaos/cloud-sdk release because the plugin depends on it directly.

The repository also contains legacy Python and Rust package directories. The Eliza runtime integration and npm package are the TypeScript implementation documented above.

License

MIT