> ## 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 Python API

> The Deploy class and result models from praisonai-deploy

The `Deploy` class runs, inspects, and tears down a deployment from Python.

```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
    D[Deploy] --> DE[deploy]
    D --> PL[plan]
    D --> ST[status]
    D --> DR[doctor]
    D --> DES[destroy]

    classDef cls fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef m fill:#189AB4,stroke:#7C90A0,color:#fff

    class D cls
    class DE,PL,ST,DR,DES m
```

## Quick Start

<Steps>
  <Step title="From a YAML file">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_deploy import Deploy

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

  <Step title="From a config object">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonai_deploy import Deploy, DeployConfig, DeployType

    config = DeployConfig(type=DeployType.API)
    deploy = Deploy(config, agents_file="agents.yaml")
    result = deploy.deploy()
    ```
  </Step>
</Steps>

***

## Methods

| Method                                        | Returns         | Description                                                |
| --------------------------------------------- | --------------- | ---------------------------------------------------------- |
| `Deploy.from_yaml(agents_file="agents.yaml")` | `Deploy`        | Build a `Deploy` from the `deploy:` section of a YAML file |
| `Deploy(config, agents_file="agents.yaml")`   | `Deploy`        | Build a `Deploy` from a `DeployConfig` object              |
| `deploy(background=False)`                    | `DeployResult`  | Execute the deployment                                     |
| `plan()`                                      | `dict`          | Return the planned configuration without deploying         |
| `status()`                                    | `DeployStatus`  | Return the current service state                           |
| `doctor()`                                    | `DoctorReport`  | Run readiness checks for the configured type               |
| `destroy(force=False)`                        | `DestroyResult` | Tear down the deployment                                   |

<Note>
  For `type: api`, `deploy()` spawns the generated Flask server with `sys.executable` and passes `env=os.environ.copy()`, so the child inherits the caller's interpreter and environment (`OPENAI_API_KEY`, etc.). No extra wiring is required to reach `/chat`.
</Note>

***

## Result Models

Each operation returns a typed model.

### DeployResult

| Field      | Type             | Description                      |
| ---------- | ---------------- | -------------------------------- |
| `success`  | `bool`           | Whether the deployment succeeded |
| `message`  | `str`            | Human-readable result message    |
| `url`      | `Optional[str]`  | Deployed service URL             |
| `error`    | `Optional[str]`  | Error message if it failed       |
| `metadata` | `Dict[str, Any]` | Additional metadata              |

### DeployStatus

| Field               | Type             | Default      | Description                                                                                                  |
| ------------------- | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
| `state`             | `ServiceState`   | *(required)* | `running` / `stopped` / `pending` / `failed` / `not_found` / `unknown`                                       |
| `url`               | `Optional[str]`  | `None`       | Service URL/endpoint                                                                                         |
| `message`           | `str`            | `""`         | Status message                                                                                               |
| `service_name`      | `Optional[str]`  | `None`       | Service name                                                                                                 |
| `provider`          | `Optional[str]`  | `None`       | `api` / `docker` / `<any registered provider>`. Plugin providers surface here too, as their normalised name. |
| `region`            | `Optional[str]`  | `None`       | Deployment region                                                                                            |
| `healthy`           | `bool`           | `False`      | Whether the service is healthy                                                                               |
| `instances_running` | `int`            | `0`          | Running instances                                                                                            |
| `instances_desired` | `int`            | `0`          | Desired instances                                                                                            |
| `created_at`        | `Optional[str]`  | `None`       | Creation timestamp                                                                                           |
| `updated_at`        | `Optional[str]`  | `None`       | Last update timestamp                                                                                        |
| `metadata`          | `Dict[str, Any]` | `{}`         | Provider-specific metadata                                                                                   |

`DeployStatus.to_dict()` returns a JSON-serialisable dictionary.

***

## Programmatic APIs

The registry — not the `CloudProvider` enum — is the authority on what is deployable.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai_deploy import (
    CloudProvider,           # built-in constants (aws, azure, gcp, fly, railway, render)
    coerce_cloud_provider,   # validate a name against the registry
    list_cloud_providers,    # every deployable name (built-ins + plugins)
)
from praisonai_deploy.providers import CloudProviderRegistry
```

| Function                          | Returns                 | Description                                                                                                                                          |
| --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_cloud_providers()`          | `list[str]`             | Every deployable name now. Built-ins first (declaration order), plugins appended sorted.                                                             |
| `coerce_cloud_provider(value)`    | `CloudProvider \| str`  | A `CloudProvider` member for built-ins, a normalised lowercase `str` for plugins. Raises `ValueError` with a registry-derived list on unknown names. |
| `CloudProviderRegistry.default()` | `CloudProviderRegistry` | The shared registry. Use `list_names()`, `register(name, cls)`, and `resolve(name)` for programmatic use.                                            |

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

print(list_cloud_providers())          # ['aws', 'azure', 'gcp', 'fly', 'railway', 'render', ...]
print(coerce_cloud_provider("AWS"))    # CloudProvider.AWS  (built-in keeps enum identity)
print(coerce_cloud_provider(" gcp "))  # CloudProvider.GCP  (stripped + lowercased)
```

### DestroyResult

| Field               | Type             | Description                   |
| ------------------- | ---------------- | ----------------------------- |
| `success`           | `bool`           | Whether the destroy succeeded |
| `message`           | `str`            | Result message                |
| `resources_deleted` | `List[str]`      | Deleted resource identifiers  |
| `error`             | `Optional[str]`  | Error message if it failed    |
| `metadata`          | `Dict[str, Any]` | Additional metadata           |

***

## Common Patterns

Read the status as JSON.

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

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

Plan before deploying.

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

deploy = Deploy.from_yaml("agents.yaml")
print(deploy.plan())  # dict describing the planned deployment
```

Tear down when finished.

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

deploy = Deploy.from_yaml("agents.yaml")
result = deploy.destroy(force=True)
print(result.resources_deleted)
```

<Note>
  For `type: api`, `destroy()` finds the process on the API port with `netstat -ano` on Windows and `lsof -ti :<port>` on macOS/Linux, then terminates it with `taskkill /PID <pid> /F` or `SIGTERM` respectively. A missing discovery binary is treated as "no server running" (`success=True`); PIDs that can't be killed leave `success=False` with the survivors in `error=`.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Check success before reading url">
    `DeployResult.url` is only set when `success` is `True`. Branch on `result.success` first.
  </Accordion>

  <Accordion title="Use to_dict() for logs and APIs">
    `DeployStatus.to_dict()` returns plain JSON types, ready to serialise into logs or an HTTP response.
  </Accordion>

  <Accordion title="Import from praisonai_deploy">
    Use `from praisonai_deploy import Deploy` — the `praisonai.deploy` path is a compatibility shim only.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Config Reference" icon="sliders" href="/docs/docs/features/deploy/config-reference">
    DeployConfig and nested config models
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/docs/docs/features/deploy/cli">
    The praisonai deploy command group
  </Card>

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