Deploy Config Reference

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

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

python

from praisonai_deploy import DeployConfig, DeployType

config = DeployConfig(type=DeployType.API)

Warning

Strict validation. APIConfig, DockerConfig, and CloudConfig reject unknown fields (extra="forbid"), and the deploy: section rejects unknown top-level keys. Allowed deploy: keys are type, api, docker, cloud, and agents. A misspelled field or section used to deploy silently with all-defaults — it now fails fast.

yaml

deploy:
  type: cloud
  cloud:
    provider: aws
    region: us-east-1
    service_name: my-agent-service
    clustor_name: prod-shared-cluster   # typo — should be cluster_name

text

❌ Validation failed: 1 validation error for CloudConfig
clustor_name
  Extra inputs are not permitted

Fix the spelling to cluster_name. Landed in PraisonAI PR #4308 (issue #4306).

Diagram

Quick Start

API config

python

from praisonai_deploy import DeployConfig, DeployType

config = DeployConfig(type=DeployType.API)  # APIConfig() defaults filled in

Cloud config

python

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",
    ),
)

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"

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

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

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.

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). Type is optional at the dataclass level, but the Azure provider requires it at deploy/status/destroy time — the call returns a failure result if unset.
`subscription_id`	`Optional[str]`	`None`	Subscription ID (Azure). Type is optional at the dataclass level, but the Azure provider requires it at deploy/status/destroy time — the call returns a failure result if unset. Threaded onto every `az` command via `--subscription`.
`project_id`	`Optional[str]`	`None`	Project ID (GCP). Type is optional at the dataclass level, but the GCP provider requires it at deploy/status/destroy time — the call returns a failure result if unset.

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

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.

Always set cloud fields explicitly

provider, region, and service_name are required for cloud deployments and have no defaults.

Quote cpu and memory values

cpu and memory are strings ("256", "512"), not integers — quote them in YAML.

Python API

Deploy class and result models

Quick Start

Minimal agents.yaml per type

Custom Providers

Deploy Config Reference

Quick Start

DeployConfig

Enums

DeployType

CloudProvider

CloudProviderLike

ServiceState

APIConfig

DockerConfig

Sibling api: block (Docker only)

Generated Gunicorn CMD

CloudConfig

AgentConfig

Best Practices

Related

Sibling `api:` block (Docker only)