/packages/docs/cloud/containers.mdx

---
title: Containers
description: Deploy custom Docker containers on Eliza Cloud.
---

# Containers

Deploy custom Docker images on Eliza Cloud managed container infrastructure.

## Overview

Container deployment provides:

- **Custom runtimes**: Run your own Docker image.
- **Project identity**: Use `projectName` as the stable deployment identifier in requests.
- **Managed health checks**: Poll your `healthCheckPath` and update status.
- **Logs and metrics**: Fetch logs and runtime metrics through the API.
- **Earnings-first billing**: Daily hosting can be paid from redeemable earnings before org credits.

## Quick Start

```bash
curl -X POST "https://www.elizacloud.ai/api/v1/containers" \
  -H "Authorization: Bearer $ELIZA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service",
    "projectName": "my-service",
    "image": "ghcr.io/acme/my-service:latest",
    "port": 3000,
    "cpu": 1792,
    "memoryMb": 1792,
    "healthCheckPath": "/health",
    "environmentVars": {
      "NODE_ENV": "production"
    }
  }'
```

## Deploying a Container

<Steps>
<Step title="Build and push your image">

Push to a registry that Cloud nodes can pull from, such as GHCR, Docker Hub, or your private registry.

</Step>

<Step title="Create the container">

Send `image`, `projectName`, `port`, resources, and any `environmentVars`.

</Step>

<Step title="Poll status">

Poll `GET /api/v1/containers/{id}` until `data.status` is `running` or `failed`.

</Step>

<Step title="Patch your Cloud app">

For app projects, patch the Eliza Cloud app `app_url` and `allowed_origins` to the running container URL.

</Step>
</Steps>

## Deployment Configuration

```json
{
  "name": "my-service",
  "projectName": "my-service",
  "image": "ghcr.io/acme/my-service:latest",
  "port": 3000,
  "cpu": 1792,
  "memoryMb": 1792,
  "healthCheckPath": "/health",
  "environmentVars": {
    "PORT": "3000",
    "ELIZA_APP_ID": "uuid-abc123"
  }
}
```

| Field | Description |
| ----- | ----------- |
| `name` | Human-readable container name. |
| `projectName` | Stable project identifier used for deployment records and project-scoped volumes. |
| `image` | Full image reference pulled directly by the container backend. |
| `port` | Application port. Default: 3000. |
| `cpu` | CPU units used for API compatibility and billing. Default: 1792. |
| `memoryMb` | Memory in MB. Default: 1792. |
| `healthCheckPath` | HTTP health path. Default: `/health`. |
| `environmentVars` | String key/value environment variables. |

<Info>
  The current public create-container payload uses `image`, not the older `ecr_image_uri` field. The backend pulls the image directly on the target Docker node.
</Info>

## Billing

Daily container billing calculates hosting cost and, when `payAsYouGoFromEarnings` is enabled for the organization, debits the owner's redeemable earnings first. Any remainder falls through to organization credits.

When earnings-first billing is off, hosting bills come only from credits and earnings remain available for token cashout.

## Best Practices

- Expose a fast `/health` route.
- Container scaling is currently fixed at one replica.
- Keep secrets server-side and pass only required runtime env vars.
- Use a stable `projectName`; project-scoped persistent data is keyed by organization and project name.
- For monetized apps, pass `ELIZA_APP_ID` to your container and patch the Cloud app URL after deploy.

## Next Steps

<CardGroup>
  <CardGroup.Card title="Monetized Apps" href="/cloud/monetized-apps">
    Deploy an earning app
  </CardGroup.Card>
  <CardGroup.Card title="Containers API" href="/cloud/api/containers">
    API reference
  </CardGroup.Card>
  <CardGroup.Card title="Billing" href="/cloud/billing">
    Understand hosting costs
  </CardGroup.Card>
</CardGroup>