elizaos--eliza/packages/docs/cloud/api/containers.mdx

---
title: Containers
description: Deploy and manage containers on Eliza Cloud.
---

# Containers

Deploy and manage Docker containers. The current public API accepts a generic image reference in `image`; it is not limited to ECR images.

## List Containers

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/containers</span>
</div>

Get all containers for your organization.

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "my-app",
      "project_name": "my-app",
      "status": "running",
      "image_tag": "ghcr.io/acme/my-app:latest",
      "load_balancer_url": "https://my-app.example.com",
      "cpu": 1792,
      "memory": 1792,
      "port": 3000,
      "desired_count": 1,
      "billing_status": "active",
      "created_at": "2026-05-05T10:30:00Z"
    }
  ]
}
```

---

## Create Container

<div className="api-endpoint">
  <span className="method-badge method-badge-post">POST</span>
  <span className="path">/api/v1/containers</span>
</div>

Deploy a new container. Returns a container record.

### Request

The request body is **camelCase** — the server validates with a strict schema that **silently drops unknown keys**, so a snake_case key (e.g. `environment_vars`) is discarded and your `ELIZA_APP_ID` never reaches the container.

```json
{
  "name": "My App",
  "projectName": "my-app",
  "image": "ghcr.io/elizaos/example-edad:showcase",
  "port": 3000,
  "cpu": 1792,
  "memoryMb": 1792,
  "healthCheckPath": "/health",
  "environmentVars": {
    "PORT": "3000",
    "ELIZA_APP_ID": "uuid-abc123"
  }
}
```

### Parameters

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `name` | string | yes | Display name. |
| `projectName` | string | no | Stable project identifier. |
| `image` | string | yes | Full image reference, for example `ghcr.io/owner/repo:tag`. |
| `port` | integer | no | Container port. Default: 3000. |
| `cpu` | integer | no | CPU units. Default: 1792. |
| `memoryMb` | integer | no | Memory in MB. Default: 1792. |
| `healthCheckPath` | string | no | Health check endpoint. Default: `/health`. |
| `environmentVars` | object | no | String environment variables (this is where `ELIZA_APP_ID` belongs). |

### Response

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My App",
    "project_name": "my-app",
    "status": "deploying",
    "load_balancer_url": "https://my-app.example.com",
    "cpu": 1792,
    "memory": 1792,
    "port": 3000,
    "desired_count": 1,
    "health_check_path": "/health"
  }
}
```

<Warning>
  Container deployments require sufficient credits or available earnings and are subject to organization quotas.
</Warning>

---

## Get Container

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/containers/{"{id}"}</span>
</div>

Get container details and deployment status.

### Status Values

| Status | Description |
| ------ | ----------- |
| `pending` | Deployment initiated. |
| `deploying` | Image pull or container start in progress. |
| `running` | Container is healthy and accessible. |
| `failed` | Deployment failed; check `error_message` and logs. |
| `stopped` | Container stopped. |
| `suspended` | Billing or policy suspension. |

---

## Update Container

<div className="api-endpoint">
  <span className="method-badge method-badge-patch">PATCH</span>
  <span className="path">/api/v1/containers/{"{id}"}</span>
</div>

Patch bodies are action-discriminated. Send exactly one of these shapes:

```json
{ "action": "restart" }
```

```json
{
  "action": "setEnv",
  "environmentVars": {
    "PORT": "3000",
    "ELIZA_APP_ID": "uuid-abc123"
  }
}
```

```json
{
  "action": "scale",
  "desiredCount": 1
}
```

The current backend supports `desiredCount: 1`.

---

## Delete Container

<div className="api-endpoint">
  <span className="method-badge method-badge-delete">DELETE</span>
  <span className="path">/api/v1/containers/{"{id}"}</span>
</div>

Stop and delete a container.

---

## Container Logs

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/containers/{"{id}"}/logs</span>
</div>

Get plain-text container logs.

### Query Parameters

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `tail` | integer | Number of lines. Default: 200. |

---

## Container Metrics

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/containers/{"{id}"}/metrics</span>
</div>

Get container metrics.

---

## Quota

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/containers/quota</span>
</div>

Get organization container quota.

---

## Credentials

<div className="api-endpoint">
  <span className="method-badge method-badge-post">POST</span>
  <span className="path">/api/v1/containers/credentials</span>
</div>

Create or fetch registry credential helper data when configured. Public container creation can also use any image reference that the target node can pull.