> ## 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 to Fly.io

> Deploy PraisonAI to Fly.io in one command

Deploy your agents to Fly.io with a starter `fly.toml` and a single deploy command.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Fly.io Deploy"
        Create[💻 create --template fly] --> Edit[📝 Edit fly.toml]
        Edit --> Deploy[🚀 deploy fly]
        Deploy --> App[✅ app.fly.dev]
    end

    classDef cli fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef edit fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class Create cli
    class Edit edit
    class Deploy,App ok
```

<Warning>
  Starter templates ship in the git checkout, **not** in the PyPI wheel (`MANIFEST.in` excludes `infra/`). Run `create` from a monorepo checkout, or set `PRAISONAI_STARTERS_ROOT` / `PRAISONAI_INFRA_ROOT`.
</Warning>

## Quick Start

<Steps>
  <Step title="Scaffold the project">
    The starter drops `fly.toml` and `agents.yaml` into the current directory.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy create --template fly
    ```
  </Step>

  <Step title="Authenticate with Fly">
    Set a token or log in with flyctl.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export FLY_API_TOKEN="..."
    # or: fly auth login
    ```
  </Step>

  <Step title="Deploy">
    Deploy the app; pass a region if you want to override the default.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy fly
    ```
  </Step>
</Steps>

***

## How It Works

The command shells out to `flyctl deploy`, so authentication follows a clear precedence.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as deploy fly
    participant Fly as flyctl

    User->>CLI: praisonai deploy fly
    CLI->>CLI: Resolve auth (FLY_API_TOKEN → FLY_ACCESS_TOKEN → whoami)
    CLI->>Fly: flyctl deploy --app <name> --remote-only
    Fly-->>User: https://<app>.fly.dev
```

**Auth precedence:** `FLY_API_TOKEN` → `FLY_ACCESS_TOKEN` → `flyctl auth whoami` fallback (a `fly auth login` session stores its token in the flyctl config, not the environment).

***

## Command Options

| Argument / Flag     | Default             | Description           |
| ------------------- | ------------------- | --------------------- |
| `FILE` (positional) | `agents.yaml`       | Agent file to deploy. |
| `--region` / `-r`   | *(from `fly.toml`)* | Fly region override.  |

***

## Starter `fly.toml`

The `fly` starter ships production-ready defaults.

| Setting              | Value                                    |
| -------------------- | ---------------------------------------- |
| Image                | `ghcr.io/mervinpraison/praisonai:latest` |
| `internal_port`      | `8005`                                   |
| `PRAISONAI_API_AUTH` | `enabled`                                |
| Health check         | HTTP `GET /health` every 15s             |

***

## Doctor

Check Fly readiness before deploying.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai deploy doctor --provider fly
```

<Note>
  `deploy doctor --provider fly` now runs the Fly provider's checks (flyctl on PATH + authentication) — previously this reported "Unknown provider".
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Pin the image tag for production">
    The starter uses `latest`. Swap in a released tag in `[build] image` before shipping.
  </Accordion>

  <Accordion title="Set secrets with fly secrets, not fly.toml">
    Keep `OPENAI_API_KEY` and other secrets out of Git: `fly secrets set OPENAI_API_KEY=...`.
  </Accordion>

  <Accordion title="Keep auth enabled">
    The starter sets `PRAISONAI_API_AUTH=enabled`. Leave it on and supply a token so the public app requires `Authorization: Bearer`.
  </Accordion>
</AccordionGroup>

***

## Add a New Provider

Provider entry points are pluggable via `pyproject.toml`. To add your own, register it in the provider registry (`providers/_registry.py`) and implement the `BaseProvider` interface (`doctor`, `plan`, `deploy`, `status`, `destroy`).

***

## Related

<CardGroup cols={2}>
  <Card title="Deploy Templates" icon="file-code" href="/docs/docs/features/create-templates">
    Scaffold the fly starter.
  </Card>

  <Card title="Deploy to Railway" icon="train" href="/docs/docs/features/railway">
    Another one-command PaaS target.
  </Card>
</CardGroup>