plugin-elizacloud

Imported from afu20260324/eliza (plugins/plugin-elizacloud/AGENTS.md). Install upstream with npx skills add afu20260324/eliza --skill plugin-elizacloud. Copyright stays with the author.

@elizaos/plugin-elizacloud

Eliza Cloud integration — multi-model inference, container provisioning, agent bridge, and billing for elizaOS agents.

Purpose / role

Connects an Eliza agent to Eliza Cloud for hosted AI inference (text, embeddings, TTS, STT, image), container lifecycle management, real-time agent bridging via WebSocket, and billing/credit flows. Auto-enables when ELIZAOS_CLOUD_API_KEY or ELIZAOS_CLOUD_ENABLED=true is present (see auto-enable.ts). This plugin has priority 50, which means it wins the default text-generation slot over other direct provider plugins (priority 0) when no explicit routing preference is configured — unless the host writes ELIZAOS_CLOUD_USE_INFERENCE=false (applyCloudConfigToEnv), in which case the chat-brain handlers (TEXT_*, RESPONSE_HANDLER, ACTION_PLANNER) are not registered at all and only the capability handlers (IMAGE, IMAGE_DESCRIPTION, TEXT_TO_SPEECH, TRANSCRIPTION, embeddings, RESEARCH) stay active. This capability-only mode is how an agent keeps Cloud image/media/TTS while an external provider (a CLI/SDK subscription brain, a local model) owns the text brain (elizaOS/eliza#10819).

The plugin has two distinct export surfaces:

• elizaOSCloudPlugin (src/index.ts) — inference model handlers, cloud providers, and cloud services. Safe in both browser and Node.
• elizaCloudRoutePlugin (src/plugin.ts) — registers /api/cloud/* HTTP routes. Node-only; loaded lazily via src/register-routes.ts.

Plugin surface

Model handlers

Two registration groups (elizaOS/eliza#10819):

Capability handlers — always registered (static models map). These don't compete with the chat brain and must survive an external text provider:

Chat-brain handlers — registered from init() (registerTextInferenceModels, src/index.ts), skipped when the host writes ELIZAOS_CLOUD_USE_INFERENCE=false (registered when it is true or unset — unset preserves standalone plugin use):

Providers

Services (started in dependency order)

Events

Forwards per-inference token and USD spend to the Cloud metering endpoint when the container is a hosted agent. Inactive otherwise.

Routes (via elizaCloudRoutePlugin)

All paths use rawPath: true. Handled by three route groups:

• Status (handleCloudStatusRoutes): GET /api/cloud/status, GET /api/cloud/credits
• Cloud routes (handleCloudRoute): login, disconnect, relay-status, agents provisioning/connect/shutdown, coding-container create/sync/promotions
• Billing proxy (handleCloudBillingRoute): GET|POST|PUT|PATCH|DELETE /api/cloud/billing/:path* — forwards to authenticated Cloud API

Layout

plugins/plugin-elizacloud/
  src/
    index.ts                        Main plugin object (elizaOSCloudPlugin)
    index.node.ts                   Node-specific re-exports
    index.browser.ts                Browser-compatible build entry
    plugin.ts                       Route-only plugin (elizaCloudRoutePlugin)
    register-routes.ts              Lazy-loads route plugin via registerAppRoutePluginLoader
    init.ts                         OpenAI-compatible client initialization
    auto-enable.ts                  Auto-enable check (reads ELIZAOS_CLOUD_API_KEY / ELIZAOS_CLOUD_ENABLED)
    cloud-setup.ts                  Interactive Cloud setup flow (runCloudSetup)
    cloud-voice-catalog.ts          Fetches available TTS voice catalog from Cloud
    models/
      text.ts                       Text generation handlers for all model tiers
      embeddings.ts                 TEXT_EMBEDDING handler
      image.ts                      IMAGE and IMAGE_DESCRIPTION handlers
      speech.ts                     TEXT_TO_SPEECH handler + CloudTtsUnavailableError
      research.ts                   RESEARCH handler
      transcription.ts              TRANSCRIPTION handler
      tokenization.ts               TEXT_TOKENIZER_ENCODE/DECODE handlers
      index.ts                      Re-exports all model handlers
    services/
      cloud-auth.ts                 CloudAuthService (CLOUD_AUTH)
      cloud-bootstrap.ts            CloudBootstrapServiceImpl (CLOUD_BOOTSTRAP)
      cloud-managed-gateway-relay.ts CloudManagedGatewayRelayService (CLOUD_MANAGED_GATEWAY_RELAY)
      cloud-model-registry.ts       CloudModelRegistryService (CLOUD_MODEL_REGISTRY)
      cloud-container.ts            CloudContainerService (CLOUD_CONTAINER)
      cloud-bridge.ts               CloudBridgeService (CLOUD_BRIDGE)
      cloud-backup.ts               CloudBackupService (CLOUD_BACKUP)
      cloud-credential-provider.ts  CloudCredentialProvider (workflow_credential_provider)
    cloud-providers/
      cloud-status.ts               elizacloud_status provider
      credit-balance.ts             elizacloud_credits provider
      container-health.ts           elizacloud_health provider
      model-registry.ts             elizacloud_models provider
    routes/
      cloud-routes.ts               Core cloud login/disconnect/agent routes
      cloud-routes-autonomous.ts    Autonomous-mode cloud route handler
      cloud-status-routes.ts        /api/cloud/status and /api/cloud/credits
      cloud-status-routes-autonomous.ts  Autonomous-mode status route handler
      cloud-billing-routes.ts       /api/cloud/billing/* proxy
      cloud-relay-routes.ts         Relay-status route
      cloud-provisioning.ts         isCloudProvisionedContainer helper
      cloud-coding-container-routes.ts  Coding-container management
      cloud-compat-routes.ts        Compat route shims
      cloud-features-routes.ts      Feature-flag routes
      travel-provider-relay-routes.ts   Travel provider relay routes
      home-remote-runner-access-url.ts  Remote runner access URL helper
    cloud/
      auth.ts                       Auth helpers
      auth-service-types.ts         CloudAuthApiKeyService interface, normalizeCloudApiKey, isCloudAuthApiKeyService
      backup.ts                     Backup helpers
      base-url.ts                   resolveCloudApiBaseUrl, normalizeCloudSiteUrl
      bridge-client.ts              ElizaCloudClient, CloudWalletDescriptor
      cloud-api-key.ts              resolveCloudApiKey, resolveCloudApiBaseUrl, normalizeCloudSecret
      cloud-manager.ts              CloudManager orchestrator
      cloud-proxy.ts                Proxy utilities
      cloud-wallet.ts               Wallet descriptor types
      clack-observer.ts             ClackObserver (interactive CLI setup feedback)
      null-observer.ts              NullCloudSetupObserver
      setup-observer.ts             CloudSetupObserver interface
      reconnect.ts                  Reconnect helpers
      validate-url.ts               validateCloudBaseUrl
      duffel-client.ts              Duffel travel/flight booking client (searchFlights, createOrder, readDuffelConfigFromEnv, DuffelConfigError)
      lifeops-schedule-sync-client.ts  LifeOps schedule sync client (resolveLifeOpsScheduleSyncConfig)
      lifeops-schedule-sync-contracts.ts  LifeOps schedule sync contract types
      managed-payment-clients.ts    Managed payment client helpers
      x402-payment-handler.ts       x402 payment protocol handler (parseX402Response, requestPayment, PaymentRequiredError)
      index.ts                      Barrel
    lib/
      cloud-connection.ts           CloudAuthLike interface
      cloud-secrets.ts              getCloudSecret, clearCloudSecrets, scrubCloudSecretsFromEnv
      config-env.ts                 Env-to-config mapping
      config-like.ts                ElizaConfig type
      credential-type-map.ts        credTypeToConnector mapping
      feature-flags.ts              Feature flag helpers
      http.ts                       sendJson HTTP helper
      server-cloud-tts.ts           TTS compat layer, resolveCloudTtsBaseUrl
      state-paths.ts                State directory path helpers
      tts-debug.ts                  TTS debug utilities
    providers/
      openai.ts                     createOpenAIClient (Vercel AI SDK OpenAI-compatible adapter)
    utils/
      cloud-api.ts                  CloudApiClient — base HTTP client for Cloud API
      sdk-client.ts                 createCloudApiClient, createElizaCloudClient
      waifu-metering.ts             createWaifuMeteringHandler (MODEL_USED event bridge)
      config.ts                     Model string resolution helpers (getNanoModel, getLargeModel, …)
      events.ts                     emitModelUsageEvent, ModelUsageEventMeta
      helpers.ts                    Misc internal helpers
      responses-output.ts           extractResponsesOutputText (Responses API output parser)
      cloud/sdk/                    Internal SDK surface wrappers
    types/
      cloud.ts                      CloudContainer, DevicePlatform, DEFAULT_CLOUD_CONFIG, and all Cloud API types
      index.ts                      Type barrel
  __tests__/
    unit/                           Unit tests (no live API)
    integration/                    Integration tests
    *.test.ts                       Feature-level test suites
  auto-enable.ts                    Auto-enable entry point (package.json elizaos.plugin.autoEnableModule)
  build.ts                          Dual-target (node + browser) build script
  package.json

Commands

bun run --cwd plugins/plugin-elizacloud build       # compile node + browser bundles
bun run --cwd plugins/plugin-elizacloud typecheck   # type check only (tsc --noEmit)
bun run --cwd plugins/plugin-elizacloud test        # run all tests via vitest
bun run --cwd plugins/plugin-elizacloud test:unit   # unit tests only
bun run --cwd plugins/plugin-elizacloud test:integration  # integration tests only
bun run --cwd plugins/plugin-elizacloud test:e2e    # live smoke test via app-core script
bun run --cwd plugins/plugin-elizacloud lint        # biome check --write --unsafe
bun run --cwd plugins/plugin-elizacloud clean       # rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo

Config / env vars

All settings are optional except ELIZAOS_CLOUD_API_KEY (required for any authenticated call).

Required

Optional — core

Optional — model tiers (each has a fallback bare env alias)

Optional — embeddings

Optional — image / audio

Browser-only proxy vars (no secrets in client bundles)

How to extend

Add a model handler

1. Add a handler function in the appropriate file under src/models/.
2. Export it from src/models/index.ts.
3. Register it in the models map in src/index.ts keyed by the ModelType constant.
4. Use createCloudApiClient(runtime) for raw API-base calls (see src/utils/sdk-client.ts).
5. Call emitModelUsageEvent(runtime, type, prompt, usage, meta) after each inference call.

Add a provider

1. Create a new file in src/cloud-providers/ exporting a Provider object.
2. Export it from src/cloud-providers/index.ts.
3. Add it to the providers array in src/index.ts.
4. Gate it with contextGate so it only fires in relevant context windows.

Add a service

1. Create a new file in src/services/ with a class extending Service from @elizaos/core.
2. Set a static serviceType string (used for runtime.getService(...) lookups).
3. Add it to the services array in src/index.ts in dependency order.
4. Add a matching await runtime.getService(YourService.serviceType)?.stop() line in dispose().

Conventions / gotchas

• No direct fetch() for Cloud API calls. Use createCloudApiClient(runtime) or createElizaCloudClient(runtime) from src/utils/sdk-client.ts. The one exception is the plugin test suite downloading a public audio fixture.
• ELIZAOS_CLOUD_ENABLED gates infrastructure services. When false, only inference model handlers are active. Container, bridge, backup, and relay services start only when this flag is true.
• Browser build is separate. src/index.browser.ts is the entry for dist/browser/. It must not import Node-only modules. The route plugin (src/plugin.ts) is Node-only and is excluded from the browser bundle.
• Routes use rawPath: true. All /api/cloud/* routes bypass the plugin-name prefix so paths stay stable.
• TTS routing precedence. This plugin's priority (50) does not govern TTS routing. The router-handler in plugin-local-inference runs at MAX_SAFE_INTEGER priority and enforces the prefer-local policy. Cloud TTS is a fallback; CloudTtsUnavailableError (from src/models/speech.ts) signals the router to try the next provider.
• Cloud STT gate mirrors the TTS gate. handleTranscription serves when a Cloud API key is present AND (ELIZAOS_CLOUD_ENABLED OR ELIZAOS_CLOUD_USE_STT) is truthy — isCloudSttAvailable in src/utils/config.ts. Otherwise it throws CloudSttUnavailableError so the local-inference router falls through to the next TRANSCRIPTION provider. audioUrl/string inputs are fetched through core's fetchWithSsrfGuard.
• Cloud TTS availability gate ≠ core isCloudConnected. handleTextToSpeech and fetchCloudVoiceCatalog serve when a Cloud API key is present AND (ELIZAOS_CLOUD_ENABLED OR ELIZAOS_CLOUD_USE_TTS) is truthy — isCloudTtsAvailable in src/utils/config.ts. The USE_TTS leg is what keeps Cloud TTS alive in capability-only mode, where applyCloudConfigToEnv deliberately leaves ELIZAOS_CLOUD_ENABLED unset (many consumers read ENABLED as "cloud is the text brain"). Do not "simplify" this back to core isCloudConnected — that regates TTS on inference and reopens the capability-only gap (elizaOS/eliza#10961 follow-up).
• Services start in dependency order. CloudAuthService must be first; every other service calls runtime.getService("CLOUD_AUTH"). dispose() stops them in reverse order.
• CloudBootstrapService fails closed. getExpectedIssuer() throws when ELIZA_CLOUD_ISSUER is unset. Never add a silent default.
• No as casts or ?? 0 fallbacks for missing pipeline data. Follow the architecture rules in AGENTS.md at the repo root.

Verification

Follow the repository-wide verification and evidence standard in the root CLAUDE.md. Run the package's relevant build, typecheck, lint, and test commands, then exercise the real integration boundary changed by the work. Inspect the produced domain artifacts and failure behavior; do not substitute mocked success for the system under test.