> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Config Reference

> Every DeployConfig field, type, and default from praisonai-deploy

`DeployConfig` and its nested models define exactly what a deployment does.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_deploy import DeployConfig, DeployType

config = DeployConfig(type=DeployType.API)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    DC[DeployConfig] --> API[APIConfig]
    DC --> DK[DockerConfig]
    DC --> CL[CloudConfig]
    DC --> AG[AgentConfig list]

    classDef root fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef sub fill:#6366F1,stroke:#7C90A0,color:#fff

    class DC root
    class API,DK,CL,AG sub
```

## Quick Start

<Steps>
  <Step title="API config">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_deploy import DeployConfig, DeployType

    config = DeployConfig(type=DeployType.API)  # APIConfig() defaults filled in
    ```
  </Step>

  <Step title="Cloud config">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_deploy import DeployConfig, DeployType
    from praisonai_deploy import CloudProvider
    from praisonai_deploy.models import CloudConfig

    config = DeployConfig(
        type=DeployType.CLOUD,
        cloud=CloudConfig(
            provider=CloudProvider.GCP,
            region="us-central1",
            service_name="my-agent",
        ),
    )
    ```
  </Step>
</Steps>

***

## DeployConfig

| Field    | Type                          | Default                                             | Description                                                                                       |
| -------- | ----------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `type`   | `DeployType`                  | *(required)*                                        | Deployment type                                                                                   |
| `api`    | `Optional[APIConfig]`         | auto when `type="api"`; optional on `type="docker"` | API server config. On `docker`, configures the generated in-container server. Ignored on `cloud`. |
| `docker` | `Optional[DockerConfig]`      | auto when `type="docker"`                           | Docker config                                                                                     |
| `cloud`  | `Optional[CloudConfig]`       | **required** when `type="cloud"`                    | Cloud config                                                                                      |
| `agents` | `Optional[List[AgentConfig]]` | `None`                                              | Agent configurations                                                                              |

Validation rules:

* `type="cloud"` requires a `cloud:` section, otherwise raises `ValueError("cloud config required for cloud deployment type")`.
* `type="api"` fills in `APIConfig()` defaults when omitted.
* `type="docker"` fills in `DockerConfig()` defaults when omitted.

***

## Enums

### DeployType

| Value      | Meaning                                                  |
| ---------- | -------------------------------------------------------- |
| `"api"`    | Local / hosted Flask API server                          |
| `"docker"` | Build (and optionally push) a Docker image               |
| `"cloud"`  | Deploy to AWS ECS / Azure Container Apps / GCP Cloud Run |

### CloudProvider

`"aws"` · `"azure"` · `"gcp"` · `"fly"` · `"railway"` · `"render"`

<Note>
  This enum names the **built-ins only** — it is *not* the list of deployable providers. An enum can't be extended at runtime, so the authority is `praisonai_deploy.providers.list_cloud_providers()`. Validate a name with [`coerce_cloud_provider()`](/docs/docs/features/deploy/python-api), and add your own targets via [Custom cloud providers](/docs/docs/features/deploy/custom-providers).
</Note>

### CloudProviderLike

`CloudProviderLike = Union[CloudProvider, str]`

The accepted type for `provider`. Built-ins keep their enum identity on the way out (`config.provider is CloudProvider.AWS`); plugin providers come back as normalised lowercase strings.

### ServiceState

`running` · `stopped` · `pending` · `failed` · `not_found` · `unknown`

***

## APIConfig

| Field          | Type            | Default       | Description                        |
| -------------- | --------------- | ------------- | ---------------------------------- |
| `host`         | `str`           | `"127.0.0.1"` | Server host                        |
| `port`         | `int`           | `8005`        | Server port                        |
| `workers`      | `int`           | `1`           | Number of worker processes         |
| `cors_enabled` | `bool`          | `True`        | Enable CORS                        |
| `auth_enabled` | `bool`          | `True`        | Enable authentication              |
| `auth_token`   | `Optional[str]` | `None`        | Authentication token               |
| `reload`       | `bool`          | `False`       | Enable auto-reload for development |

***

## DockerConfig

| Field        | Type                       | Default              | Description                        |
| ------------ | -------------------------- | -------------------- | ---------------------------------- |
| `image_name` | `str`                      | `"praisonai-app"`    | Docker image name                  |
| `tag`        | `str`                      | `"latest"`           | Docker image tag                   |
| `base_image` | `str`                      | `"python:3.11-slim"` | Base Docker image                  |
| `expose`     | `List[int]`                | `[8005]`             | Ports to expose                    |
| `registry`   | `Optional[str]`            | `None`               | Docker registry URL                |
| `push`       | `bool`                     | `False`              | Push image to registry after build |
| `build_args` | `Optional[Dict[str, str]]` | `None`               | Docker build arguments             |

### Sibling `api:` block (Docker only)

`type: docker` accepts an optional sibling `api:` block that configures the API server the container will run. Fields are the same as `APIConfig` above.

| Field                 | Effect inside the container                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `host` / `port`       | Bind the generated Flask server                                                                         |
| `cors_enabled`        | Enable CORS                                                                                             |
| `auth_enabled: false` | Injects `PRAISONAI_API_AUTH=disabled` into the container so `/chat` is reachable without a bearer token |
| `auth_token`          | Sets the accepted bearer token                                                                          |

Omitting the block runs the container with the same defaults as `type: api` — auth **on**, CORS on, port 8005.

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
deploy:
  type: docker
  docker:
    image_name: my-agent
    expose: [8005]
  api:
    host: 0.0.0.0
    port: 8005
    auth_enabled: false   # exposes /chat without a token
```

### Generated Gunicorn CMD

`type: docker` generates a Dockerfile whose `CMD` starts Gunicorn with fixed worker-timeout values tuned for agent LLM workloads.

```dockerfile theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
CMD ["gunicorn", "-b", "0.0.0.0:{port}", "-w", "1", \
     "--timeout", "120", "--graceful-timeout", "30", "api_server:app"]
```

| Flag                 | Value         | Why                                                                                                                          |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `--timeout`          | `120` seconds | Cold import + first model round-trip routinely exceed Gunicorn's 30 s default; keeps the worker alive for the first `/chat`. |
| `--graceful-timeout` | `30` seconds  | Time workers get to finish in-flight requests during a restart before being force-killed.                                    |
| `-w` (workers)       | `1`           | Existing default — one worker per container, scale horizontally instead.                                                     |

<Note>
  These values are hard-coded in `praisonai_deploy/docker.py` (constant `DEFAULT_GUNICORN_TIMEOUT`). There is no YAML knob for them yet — if you need a different worker timeout, generate the Dockerfile with `praisonai deploy plan` and edit the `CMD` line before building.
</Note>

<Note>
  The sibling `api:` block is **`type: docker`-only**. On `type: cloud` it is dropped — cloud providers shell out to external CLIs and never generate the API server.
</Note>

***

## CloudConfig

| Field             | Type                       | Default      | Description                                                                                                       |
| ----------------- | -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `provider`        | `CloudProvider \| str`     | *(required)* | Cloud provider. A built-in resolves to a `CloudProvider` member; a plugin provider is accepted as a plain string. |
| `region`          | `str`                      | *(required)* | Deployment region                                                                                                 |
| `service_name`    | `str`                      | *(required)* | Service/application name                                                                                          |
| `image`           | `Optional[str]`            | `None`       | Container image URL                                                                                               |
| `cpu`             | `Optional[str]`            | `"256"`      | CPU allocation                                                                                                    |
| `memory`          | `Optional[str]`            | `"512"`      | Memory allocation (MB)                                                                                            |
| `min_instances`   | `int`                      | `1`          | Minimum instances                                                                                                 |
| `max_instances`   | `int`                      | `10`         | Maximum instances                                                                                                 |
| `env_vars`        | `Optional[Dict[str, str]]` | `None`       | Environment variables                                                                                             |
| `cluster_name`    | `Optional[str]`            | `None`       | ECS cluster name (AWS)                                                                                            |
| `task_definition` | `Optional[str]`            | `None`       | Task definition (AWS)                                                                                             |
| `resource_group`  | `Optional[str]`            | `None`       | Resource group (Azure)                                                                                            |
| `subscription_id` | `Optional[str]`            | `None`       | Subscription ID (Azure)                                                                                           |
| `project_id`      | `Optional[str]`            | `None`       | Project ID (GCP)                                                                                                  |

<Note>
  The `provider` value is normalised (`.strip().lower()`) before validation, so `AWS`, `aws`, and `"  aws  "` all resolve to `CloudProvider.AWS`. Unknown names raise `ValueError: Invalid cloud provider: X. Must be one of: …`, where the list comes from the registry (built-ins plus any installed plugins).
</Note>

<Warning>
  **Compatibility.** Built-in serialisation is unchanged: `CloudConfig(provider="aws").model_dump()["provider"] is CloudProvider.AWS`, and `model_dump_json()` still emits `"provider":"aws"`. Because `provider` is now `CloudProvider | str`, a plugin provider is a `str` — `.value` would raise on it. Guard access the way the built-in providers do: `config.provider.value if hasattr(config.provider, "value") else str(config.provider)`.
</Warning>

***

## AgentConfig

| Field        | Type                       | Default      | Description                                |
| ------------ | -------------------------- | ------------ | ------------------------------------------ |
| `name`       | `str`                      | *(required)* | Agent name/identifier                      |
| `entrypoint` | `str`                      | *(required)* | Agent entrypoint file (e.g. `agents.yaml`) |
| `env`        | `Dict[str, str]`           | `{}`         | Environment variables                      |
| `secrets`    | `Dict[str, str]`           | `{}`         | Secret references                          |
| `ports`      | `Optional[List[int]]`      | `None`       | Ports to expose                            |
| `resources`  | `Optional[Dict[str, str]]` | `None`       | Resource requirements                      |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Let defaults fill themselves in">
    For `type="api"` and `type="docker"`, omit the nested block to accept sensible defaults. Only add fields you need to change.
  </Accordion>

  <Accordion title="Always set cloud fields explicitly">
    `provider`, `region`, and `service_name` are required for cloud deployments and have no defaults.
  </Accordion>

  <Accordion title="Quote cpu and memory values">
    `cpu` and `memory` are strings (`"256"`, `"512"`), not integers — quote them in YAML.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Python API" icon="code" href="/docs/docs/features/deploy/python-api">
    Deploy class and result models
  </Card>

  <Card title="Quick Start" icon="play" href="/docs/docs/features/deploy/quickstart">
    Minimal agents.yaml per type
  </Card>

  <Card title="Custom Providers" icon="plug" href="/docs/docs/features/deploy/custom-providers">
    Register your own cloud target
  </Card>
</CardGroup>