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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.