Eliza Cloud Integration Plan

This document defines the Eliza Cloud rollout as one of several server targets exposed through the same chooser-first startup entry point.

Product paths

1. Local The backend runs on the user's machine with the current full-local behavior and full local permissions.

2. Eliza Cloud The frontend provisions and connects to a managed container through Eliza Cloud at elizacloud.ai.

3. Remote Eliza backend The frontend connects to an already running Eliza backend by address plus access key (ELIZA_API_TOKEN).

Architecture

App onboarding

• Startup begins with a server chooser, not provider selection.
• The selected server target is canonical runtime state:
  • deploymentTarget.runtime = "local" for a local server
  • deploymentTarget.runtime = "remote" for a remote or LAN server
  • deploymentTarget.runtime = "cloud" for an Eliza Cloud server
• Provider selection happens after the server target is chosen and writes canonical serviceRouting, not hosting state.
• Eliza Cloud account linkage writes linkedAccounts.elizacloud; it does not imply Eliza Cloud inference unless serviceRouting.llmText.backend = "elizacloud".
• Persist the selected server in client state so reloads and popouts keep the same backend.
• Treat Eliza Cloud-linked services as optional per-capability routes, not a global “cloud on” flag.

Self-hosted remote backend

• The backend stays the canonical Eliza API server.
• Browser clients must send a bearer token using ELIZA_API_TOKEN.
• CORS must explicitly allow the frontend origin with ELIZA_ALLOWED_ORIGINS.
• The onboarding access key shown to the user is the same value as ELIZA_API_TOKEN.

Eliza Cloud control plane

• elizacloud.ai is the canonical managed control plane.
• There is no separate Eliza-specific cloud API service.
• Eliza Cloud is the control plane, OAuth handler, billing surface, and user store.
• Managed launches redirect into app.eliza.ai with a one-time launch session that selects the hosted server target and skips manual server entry.

Browser transport

• app.eliza.ai already exchanges managed launch sessions directly with Eliza Cloud.
• The hosted Eliza frontend should use Eliza Cloud APIs directly for browser-safe managed flows.
• The local desktop/backend keeps same-origin /api/cloud/* passthrough routes so it can persist the user's Eliza Cloud API key into local config and runtime state.
• If a Eliza-owned origin is ever required for browser routing or enterprise policy, use the Cloudflare Worker proxy template in deploy/cloudflare/eliza-cloud-proxy/ instead of standing up a separate application server.

Operator checklist

Eliza app and API

• Restore chooser-first startup in the app.
• Add Eliza Cloud and Remote Eliza cloud sub-options.
• Allow the frontend client to rebind to a remote backend during onboarding.
• Persist the rebound API base for the current session.
• Update cloud defaults and user-facing copy to Eliza Cloud.
• Persist an Eliza Cloud API key during onboarding when the user chooses API-key auth.
• Separate linked Eliza Cloud auth from active inference routing.

Self-hosted remote flow

• Document secure remote backend deployment in the README.
• Document address + access-key connection flow in the README.
• Document Tailscale as the preferred private-network exposure path.
• Add a dedicated in-app "switch backend" settings surface after onboarding.
• Add a remote-backend connectivity diagnostic screen for auth/CORS/WS failures.

Eliza Cloud control plane

• Point managed launch onboarding at canonical deploymentTarget.runtime = "cloud".
• Keep Eliza-managed launch sessions flowing through Eliza Cloud.
• Make the browser-facing Eliza Cloud auth/compat endpoints callable cross-origin when needed.
• Remove active Eliza Cloud labels from the managed auth/runtime surfaces.
• Verify post-login session redirects and popup flows end-to-end against the Eliza app.

Infrastructure and release

• Run a production smoke test:
  • Local onboarding
  • Eliza Cloud provisioning
  • Remote self-host attach by URL + token
  • Desktop download flow from the homepage
• Cut a Eliza release after the hosted flow is verified on the public domain.

Remote backend deployment recipe

Use this when the user wants to host their own backend and connect from the Eliza web frontend.

1. Install Eliza on the target machine.
2. Set a non-loopback bind, a strong API token, and explicit allowed origins.
3. Expose the service over HTTPS or a private Tailscale URL.
4. In startup, choose Manually connect or a discovered remote server, then enter:
   • backend address
   • access key (ELIZA_API_TOKEN)

Recommended environment:

ELIZA_API_BIND=0.0.0.0
ELIZA_API_TOKEN=$(openssl rand -hex 32)
ELIZA_ALLOWED_ORIGINS=https://app.eliza.ai,https://eliza.ai,https://elizacloud.ai,https://www.elizacloud.ai

Optional Tailscale exposure:

tailscale serve --https=443 http://127.0.0.1:2138

For a public Tailscale-hosted URL:

tailscale funnel --https=443 http://127.0.0.1:2138

Optional Cloudflare proxy

Use this only if a Eliza-owned browser origin is required for policy or routing reasons.

1. Deploy the Worker template in deploy/cloudflare/eliza-cloud-proxy/.
2. Point the Worker at https://www.elizacloud.ai.
3. Route only browser-facing auth/compat/launch-session paths through the Worker.
4. Keep Eliza Cloud as the only upstream control plane.

The concrete proxy setup now lives in docs/eliza-cloud-deployment.md.