> ## 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 Package

> Ship agents as an API server, a Docker image, or a cloud service with praisonai-deploy

`praisonai-deploy` turns an `agents.yaml` file into a running service — a local API server, a Docker image, or a cloud deployment on AWS, Azure, GCP, Fly, Railway, Render, or any registered plugin provider.

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

deploy = Deploy.from_yaml("agents.yaml")
result = deploy.deploy()
status = deploy.status()
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "praisonai-deploy"
        Y[📄 agents.yaml] --> D[🚀 Deploy]
        D --> A[🖥️ API Server]
        D --> K[📦 Docker Image]
        D --> C[☁️ Cloud Service]
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Y input
    class D process
    class A,K,C output
```

## Install

<CodeGroup>
  ```bash Standalone theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install praisonai-deploy
  ```

  ```bash With API server theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install "praisonai-deploy[api]"
  ```

  ```bash Full umbrella theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install "praisonai[deploy]"
  ```
</CodeGroup>

`praisonai-deploy` is a tier-2 package (C14, publish slot #8). It drives host CLIs — `docker`, `aws`, `az`, and `gcloud` — directly. No boto3, Azure, or Google Cloud SDKs are required.

## Quick Start

<Steps>
  <Step title="Pick a deployment type">
    Every deployment is one of three types.

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

    deploy = Deploy.from_yaml("agents.yaml")
    ```
  </Step>

  <Step title="Deploy">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    result = deploy.deploy()
    print(result.url)
    ```
  </Step>

  <Step title="Check status">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    status = deploy.status()
    print(status.state)  # running / stopped / pending / failed / not_found / unknown
    ```
  </Step>
</Steps>

***

## Which Type?

Choose a deployment type based on where the agent runs.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{Where does<br/>it run?} -->|My machine| API[type: api]
    Start -->|A container| DOCKER[type: docker]
    Start -->|A cloud provider| CLOUD[type: cloud]

    CLOUD --> AWS[provider: aws<br/>ECS]
    CLOUD --> AZURE[provider: azure<br/>Container Apps]
    CLOUD --> GCP[provider: gcp<br/>Cloud Run]
    CLOUD --> FLY[provider: fly]
    CLOUD --> RAILWAY[provider: railway]
    CLOUD --> RENDER[provider: render]
    CLOUD --> PLUGIN[any registered plugin]

    PLUGIN --> CUSTOM[Custom cloud providers]

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef t fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef p fill:#10B981,stroke:#7C90A0,color:#fff
    classDef ext fill:#6366F1,stroke:#7C90A0,color:#fff

    class Start q
    class API,DOCKER,CLOUD t
    class AWS,AZURE,GCP,FLY,RAILWAY,RENDER p
    class PLUGIN,CUSTOM ext
```

| Type     | Runs on                                              | Best for                      |
| -------- | ---------------------------------------------------- | ----------------------------- |
| `api`    | Local Flask server                                   | Development, quick demos      |
| `docker` | A container                                          | Portable, reproducible builds |
| `cloud`  | AWS / Azure / GCP / Fly / Railway / Render / plugins | Production, autoscaling       |

PraisonAI ships six providers out of the box (`aws`, `azure`, `gcp`, `fly`, `railway`, `render`). You can add your own by publishing a package that registers under the `praisonai.deploy.providers` entry-point group — see [Custom cloud providers](/docs/docs/features/deploy/custom-providers).

***

## User Flow

A full deploy goes from validation to teardown.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    V[validate] --> DOC[doctor]
    DOC --> P[plan]
    P --> R[run]
    R --> S[status]
    S --> DESTROY[destroy]

    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef last fill:#8B0000,stroke:#7C90A0,color:#fff

    class V,DOC,P,R,S step
    class DESTROY last
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy validate --file agents.yaml   # schema check
praisonai deploy doctor --all                  # docker/aws/az/gcloud present?
praisonai deploy plan --file agents.yaml       # dry-run
praisonai deploy run --file agents.yaml        # execute
praisonai deploy status --file agents.yaml     # poll state
praisonai deploy destroy --file agents.yaml --yes  # teardown
```

***

## What's New

<Info>
  `praisonai-deploy` extracts deployment into a standalone tier-2 package. Existing `from praisonai.deploy import ...` imports keep working through backward-compatible shims. See [Migration](/docs/docs/features/deploy/migration).
</Info>

Fixes bundled in this release:

* `/chat` message forwarding now correctly forwards the user message.
* Docker builds use the correct build context, environment variables, and ports, and replace existing containers on rebuild.
* Foreground API deploys block until the process exits.
* The CLI docker shortcut merges the YAML `deploy:` section into invocation flags.
* MCP `deploy.status` accepts an explicit `config_path` argument.
* `praisonai deploy api` (foreground and `--background`) now spawns the Flask server with the same Python interpreter as the CLI (`sys.executable`), so it works on Windows and any multi-Python / venv setup. The previous bare `python` invocation could resolve to a different interpreter and fail with `ModuleNotFoundError: No module named 'flask'`.
* The generated Flask API server subprocess now inherits the parent environment (e.g. `OPENAI_API_KEY`), so the auto-generated `/chat` endpoint reaches the agent runtime without extra wiring.
* Docker deploys now honor an optional sibling `deploy.api` block — set `api.auth_enabled: false` to expose the generated `/chat` endpoint unauthenticated. Previously the block was silently dropped and the container defaulted to auth-on (PR [#3609](https://github.com/MervinPraison/PraisonAI/pull/3609)).
* Generated Docker containers now run Gunicorn with `--timeout 120 --graceful-timeout 30`. Cold-start `/chat` calls (agent import + first model round-trip) used to exceed Gunicorn's 30 s default and get SIGKILL'd mid-request; the new defaults tolerate the cold-start latency and shut workers down cleanly on restart (PR [#3630](https://github.com/MervinPraison/PraisonAI/pull/3630)).

***

## Best Practices

<AccordionGroup>
  <Accordion title="Run doctor before every cloud deploy">
    `praisonai deploy doctor --all` checks that `docker`, `aws`, `az`, and `gcloud` are installed and authenticated before you spend time on a failed deploy.
  </Accordion>

  <Accordion title="Prefer the new import path">
    Use `from praisonai_deploy import Deploy` in new code. The legacy `praisonai.deploy` path still resolves but is only kept for compatibility.
  </Accordion>

  <Accordion title="Keep secrets out of agents.yaml">
    Use `env_vars` references and provider secret stores rather than committing tokens into the YAML file.
  </Accordion>

  <Accordion title="ModuleNotFoundError: No module named 'flask' when running deploy api">
    As of PraisonAI PR #3608 the server is spawned with the same interpreter as the CLI, so this error should no longer occur on any supported install. If you still see it, verify that `pip install "praisonai-deploy[api]"` ran against the same Python you're running `praisonai` with — `python -c "import sys, flask; print(sys.executable, flask.__version__)"` should print the interpreter path the deploy CLI uses.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Quick Start" icon="play" href="/docs/docs/features/deploy/quickstart">
    Minimal agents.yaml for each deployment type
  </Card>

  <Card title="Python API" icon="code" href="/docs/docs/features/deploy/python-api">
    The Deploy class and result models
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/docs/docs/features/deploy/cli">
    Every praisonai deploy subcommand
  </Card>

  <Card title="Config Reference" icon="sliders" href="/docs/docs/features/deploy/config-reference">
    All DeployConfig fields and defaults
  </Card>

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