> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment overview

> Choose an airmux or split deployment and identify the required database, state, network, and public URL.

One release provides one Python distribution and one container image. Choose how to run that release:

| Shape                  | Purpose                                                                                    | Guide                                         |
| ---------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------- |
| `airmux` (recommended) | Full platform on one application host plus Postgres                                        | [Docker Compose](/docs/deployment/docker)     |
| Split                  | Independent webapp, control-plane, and gateway processes with separately scalable gateways | [Separate services](/docs/deployment/scaling) |
| Gateway only           | Local-file inference without Postgres, a control plane, or usage history                   | [Gateway only](/docs/deployment/gateway)      |

To evaluate `airmux` first, follow the [quickstart](/docs/quickstart), which uses the recommended shape.

For the full platform, start with `airmux` unless you need to size or restart the services independently. Split does
not permit mixed releases: every role must use the same image digest until cross-version bundle compatibility is defined.

<Columns cols={2}>
  <Card title="Docker Compose" icon="container-storage" href="/docs/deployment/docker">
    Run `airmux` and Postgres on one host.
  </Card>

  <Card title="Upgrade and rollback" icon="rotate" href="/docs/deployment/upgrades">
    Plan an upgrade and roll back from a consistent recovery point if verification fails.
  </Card>
</Columns>

Install the [`airmux` CLI](/docs/reference/cli#installation) on the machine you use to manage the instance.

## Full-platform production requirements

| Requirement             | Purpose                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------- |
| Postgres 16             | Control-plane state, bundles, usage, and audit activity                            |
| Persistent `/state`     | Gateway identity, bundle cache, provider-secret files, and pending usage           |
| `DATABASE_URL`          | Async Postgres connection; plain `postgresql://` URLs are normalized for `asyncpg` |
| `AIRMUX_CONSOLE_URL`    | Exact public origin used by browser and CLI flows                                  |
| HTTPS ingress           | Protects sessions, management keys, inference keys, and model traffic              |
| One provider credential | Required before inference can succeed                                              |

The image defaults to the `airmux` role. Its container listens on port `8080` and serves the webapp, `/api/v1`,
`/inf/v1`, `/healthz`, and `/readyz` from one origin.

## Claim the instance

The first human account becomes the instance owner. Claim a new public instance immediately after it becomes reachable:

```bash theme={null}
airmux quickstart --url https://llm.example.com
```

Until the first account is created, anyone who can reach the sign-up page can claim ownership. Public sign-up is
disabled after claim unless `AIRMUX_PUBLIC_SIGNUP=true`; invitation links still work for their invited email.

## Persist and back up

Back up Postgres and `/state` together. The state directory contains plaintext provider credential files in the default
secret-store configuration as well as gateway identity, cached bundles, and queued usage.

The `airmux` layout owns one gateway state directory. Every split gateway must have a distinct persistent directory.
Never clone a live gateway identity or share its SQLite outbox between replicas.

## Verify a deployment

```bash theme={null}
curl --fail https://llm.example.com/healthz
curl --fail https://llm.example.com/readyz
airmux doctor --control-plane-url https://llm.example.com --gateway-url https://llm.example.com
```

`quickstart` is the final proof because it performs a real inference request through the public route.

Continue with [operations](/docs/deployment/operations), [security](/docs/deployment/security), and
[upgrade and rollback](/docs/deployment/upgrades) before production traffic.