elizaos--eliza/packages/docs/cloud/apps.mdx

---
title: Apps
description: Create and manage Eliza Cloud apps for hosting, chat routing, domains, analytics, and monetization.
---

# Apps

Apps are Cloud records that connect your product to Eliza Cloud APIs. A Cloud app is separate from your deployable project and from any `@elizaos/app-*` app plugin loaded inside an Eliza runtime.

## Overview

An Eliza Cloud app provides:

- **App identity**: A stable `id` for chat routing, domains, analytics, and marketplace records.
- **API key**: A one-time key for server-side app administration.
- **Allowed origins**: The browser origins allowed to call app-owned surfaces.
- **Monetization**: Creator markup for app-scoped chat usage.
- **Domains and hosting metadata**: App URL, managed app domains, and custom domains.

Use a **project** for deployable product workspace state and container `projectName`. Use the **Cloud app** `id` when calling `/api/v1/apps/{id}/chat`.

## Launch Readiness

Container deploys and isolated app databases are behind an explicit production
gate. Staging has a CI-backed deploy proof, but production deploy is only live
after operators apply the production apps data plane, merge the
`APPS_DEPLOY_ENABLED` cutover switch, and arm the production daemon.

**Why:** the Worker flag only decides whether deploy requests enqueue real
`APP_DEPLOY` jobs. The daemon still needs the app node list, registry settings,
tenant DB admin DSN, and matching feature flag; otherwise requests can be
accepted while apps remain stuck in `building`.

See [Launch Status](/cloud/launch-status) for the current cutover checklist.

## Quick Start

```bash
curl -X POST "https://www.elizacloud.ai/api/v1/apps" \
  -H "Authorization: Bearer $ELIZA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "app_url": "https://placeholder.invalid",
    "allowed_origins": ["https://placeholder.invalid"],
    "description": "Custom AI app",
    "website_url": "https://example.com",
    "skipGitHubRepo": true
  }'
```

```json
{
  "success": true,
  "app": {
    "id": "uuid-abc123",
    "name": "My App",
    "app_url": "https://placeholder.invalid",
    "allowed_origins": ["https://placeholder.invalid"],
    "created_at": "2026-05-05T10:30:00Z"
  },
  "apiKey": "eliza_abc123..."
}
```

<Warning>
  The app API key is returned as one-time plaintext and is server-side only. Store it immediately. For user-facing chat, forward the user's bearer token to the app-scoped chat endpoint so the user's organization balance is charged.
</Warning>

## Creating an App

<Steps>
<Step title="Register the app">

Create the Cloud app with `name`, `app_url`, and optional metadata. If your container URL does not exist yet, use a placeholder URL and patch it after deployment.

</Step>

<Step title="Enable monetization">

```bash
curl -X PUT "https://www.elizacloud.ai/api/v1/apps/$APP_ID/monetization" \
  -H "Authorization: Bearer $ELIZA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monetizationEnabled": true,
    "inferenceMarkupPercentage": 100,
    "purchaseSharePercentage": 10
  }'
```

</Step>

<Step title="Deploy your project">

Deploy your project as a container with `POST /api/v1/containers` or the SDK `createContainer()` helper. Use `projectName` for the deployment identifier and pass the Cloud app ID through environment variables.

</Step>

<Step title="Patch the app URL">

```bash
curl -X PATCH "https://www.elizacloud.ai/api/v1/apps/$APP_ID" \
  -H "Authorization: Bearer $ELIZA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_url": "https://my-app.example.com",
    "allowed_origins": ["https://my-app.example.com"]
  }'
```

</Step>
</Steps>

## App-Scoped Chat

Route user chats through the Cloud app record:

```ts
const response = await fetch(`https://www.elizacloud.ai/api/v1/apps/${APP_ID}/chat`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${userStewardJwt}`,
  },
  body: JSON.stringify({
    model: "provider/model-id",
    messages: [{ role: "user", content: "Hello" }],
    stream: false,
  }),
});
```

The app-scoped endpoint charges the user's organization credit balance. If `monetizationEnabled` is true, `inferenceMarkupPercentage` is credited to the Cloud app creator's redeemable earnings.

<Info>
  `X-Affiliate-Code` is currently implemented on generic chat/message routes such as `/api/v1/chat/completions` and `/api/v1/messages`. The app-scoped route `/api/v1/apps/{id}/chat` does not currently read that header.
</Info>

## Monetization Fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `monetizationEnabled` | boolean | Enables creator earnings for the app. |
| `inferenceMarkupPercentage` | number | Creator markup on inference, 0-1000. |
| `purchaseSharePercentage` | number | Purchase share percentage, 0-100. |

Older `enabled` plus nested `pricing` payloads are not accepted by the current app monetization endpoint.

## Earnings and Hosting

Creator markup lands in redeemable earnings. Daily container billing can use those earnings first, then organization credits, when the billing setting `payAsYouGoFromEarnings` is enabled.

Redeem available earnings for elizaOS tokens from [Dashboard -> Earnings](https://elizacloud.ai/dashboard/earnings) or the [Redemptions API](/cloud/api/redemptions).

## Best Practices

- Keep admin API keys on the server.
- Forward user bearer tokens for user-facing app-scoped chat.
- Store the Cloud app `id` separately from container `projectName`.
- Patch `app_url` and `allowed_origins` after container deployment.
- Treat `databaseMode: "isolated"` as the production default for apps that need
  persistence; verify the deployed image reads the injected `DATABASE_URL`.
- Handle 402 responses by sending users to [Dashboard -> Billing](https://elizacloud.ai/dashboard/billing).

## Next Steps

<CardGroup>
  <CardGroup.Card title="Monetized Apps" href="/cloud/monetized-apps">
    Build and deploy a monetized app
  </CardGroup.Card>
  <CardGroup.Card title="App Domains" href="/cloud/app-domains">
    Configure custom domains
  </CardGroup.Card>
  <CardGroup.Card title="Containers" href="/cloud/containers">
    Deploy custom containers
  </CardGroup.Card>
  <CardGroup.Card title="Apps API" href="/cloud/api/apps">
    API reference
  </CardGroup.Card>
</CardGroup>