title: Run and maintain LQ.AI
description: Install LQ.AI, plan the maintenance work that follows, and know what to do when something goes wrong — indexed by hosting shape.
url: https://legalquants.github.io/lq-ai/operate/
checked-against: 671eab0d (2026-10-25)
status: draft
kind: explanation
sources: docs/site/operate/index.md, docs/INSTALL-MAC.md, README.md, deploy/helm/lq-ai/Chart.yaml, deploy/caddy-tailscale/README.md, deploy/reverse-proxy/README.md, deploy/tailnet-ollama/README.md, docs/site/_data/supported-shapes.yaml

This is the operator's namespace: getting LQ.AI running, keeping it running, and knowing what to do when it doesn't. Docker Compose is the reference installation, tested end to end on this site; start there, then come back for the week-two work once it's up.

## Choose an installation

Five install paths have a recipe today. Pick the one that matches how you plan to run LQ.AI — each page names what it covers and what it doesn't. Windows and corporate-cloud-specific deployment (running the stack itself on Azure, AWS, or GCP infrastructure) are not covered by a recipe yet; the gateway's [Azure OpenAI provider adapter](https://github.com/LegalQuants/lq-ai/blob/671eab0d/gateway/app/providers/azure_openai.py) is a model provider you can point the stack at, not a guide to hosting the app on Azure.

- **[macOS desktop app](/lq-ai/operate/install-macos/)** — a signed, notarized launcher for Apple Silicon. No terminal, no cloned repository.
- **[Docker Compose](/lq-ai/operate/install-docker-compose/#quick-start)** — the reference deployment: clone, edit `.env`, `docker compose up -d`.
- **[Kubernetes via Helm](/lq-ai/operate/install-helm/)** — a chart for the core chat services; it omits some background workers the Compose setup runs. Read the page before you rely on it for more than that.
- **[Reverse proxy and TLS](/lq-ai/operate/reverse-proxy-tls/)** — putting a certificate and a stable URL in front of either install above.
- **[Air-gapped / local-only inference](/lq-ai/operate/air-gapped/)** — the same Compose stack with local inference instead of a cloud key, and what's actually been verified about its network behavior.

## Which hosting shape is mine?

| Topology | Status | Recipe | Notes |
|---|---|---|---|
| macOS desktop app (Docker Desktop, Apple Silicon) | recipe published | [Read the recipe](/lq-ai/operate/install-macos/) | Checked against [`docs/INSTALL-MAC.md`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/INSTALL-MAC.md). |
| Docker Compose, cloud provider keys (Mode 1) | recipe published | [Read the recipe](/lq-ai/operate/install-docker-compose/) | Checked against [`README.md`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/README.md). |
| Docker Compose, local-only inference (Mode 2, --profile local) | recipe published | [Read the recipe](/lq-ai/operate/air-gapped/) | the compose stack brings this up; no CI job in this repository yet measures its network behavior — see the page for the egress-inventory gap. Checked against [`README.md`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/README.md). |
| Kubernetes via the in-repo Helm chart | recipe published | [Read the recipe](/lq-ai/operate/install-helm/) | the chart has no Deployment for the ingest-worker or arq-worker background workers — document ingestion and queued jobs do not run on it yet (PRD DE-327). See the page before you rely on it for anything beyond chat. Checked against [`deploy/helm/lq-ai/`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/deploy/helm/lq-ai/). |
| Reverse proxy + TLS, private tailnet (Caddy + Tailscale) | recipe published | [Read the recipe](/lq-ai/operate/reverse-proxy-tls/) | Checked against [`deploy/caddy-tailscale/README.md`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/deploy/caddy-tailscale/README.md). |
| Reverse proxy + TLS, public domain (Caddy, Traefik, or nginx with a public certificate) | recipe published | [Read the recipe](/lq-ai/operate/reverse-proxy-tls/) | Caddy, Traefik and nginx overlays under deploy/reverse-proxy/, labelled by their README as reference configurations rather than a supported production distribution; not deployed against a public domain for this site. Checked against [`deploy/reverse-proxy/README.md`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/deploy/reverse-proxy/README.md). |
| Remote GPU host running Ollama, reached over a tailnet | recipe published | [Read the recipe](/lq-ai/operate/recipes/tailnet-ollama/) | Checked against [`deploy/tailnet-ollama/README.md`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/deploy/tailnet-ollama/README.md). |
| Windows host | not tried | none | not documented in the repository as of the checked commit. |
| Hosted on a corporate cloud VM or Kubernetes cluster (Azure, AWS, GCP) | not tried | none | not documented in the repository as of the checked commit — distinct from the Azure OpenAI *inference provider* adapter, which is shipped. |

If your shape isn't on this list, treat it as untried: nothing in the repository documents it as of the checked commit. The table is rendered at build time from [`_data/supported-shapes.yaml`](https://github.com/LegalQuants/lq-ai/blob/671eab0d/docs/site/_data/supported-shapes.yaml), so what you read here and what the repository records are the same list.

## Plan the work after installation

Assign responsibility for updates, backups, storage, access, and leaked keys before you rely on a deployment. Once LQ.AI is up: [hardware sizing](/lq-ai/operate/hardware-sizing/), [backup and restore](/lq-ai/operate/backup-and-restore/), [upgrading](/lq-ai/operate/upgrade/), [rotating a leaked provider key](/lq-ai/operate/rotate-a-leaked-key/), and [triage when something is wrong](/lq-ai/operate/something-is-wrong/). [Moving or uninstalling](/lq-ai/operate/move-or-uninstall/) and the [troubleshooting index](/lq-ai/operate/troubleshooting/) round these out. The [recipes index](/lq-ai/operate/recipes/) covers a private Tailscale address, a separate Ollama computer, and monitoring — each in the same format: problem, context, steps, verify, and the refusal errors you might hit.

## Building against LQ.AI

[Headless boot](/lq-ai/operate/headless-boot/) is the one page on running the stack without the web UI — acknowledged, not supported, no compatibility promised.

## Next

- [Is LQ.AI right for your team?](/lq-ai/start/is-it-for-you/)
- [Trust centre](/lq-ai/trust/) — the security and compliance picture behind this operational one.
- [Skills](/lq-ai/skills/)