Self-Hosting Overview
What runs where, what leaves your infrastructure, and how to operate MinusX on your own hardware
MinusX is designed to run entirely on your own infrastructure. This section covers everything you need to operate it: configuration, LLM providers, and telemetry.
What runs where
MinusX is a single Next.js application — there is no separate backend service. The AI agent orchestrator runs in-process, analytics queries run in Node.js connectors inside the same container, and documents (questions, dashboards, reports) live in an embedded PGLite database (or external Postgres if you configure one).
| Component | Where it runs |
|---|---|
| Web app + API | Your container |
| AI agent orchestrator | Your container (in-process) |
| Document storage (questions, dashboards, …) | Your disk (PGLite) or your Postgres |
| Query execution | Your container → your databases |
| Warehouse credentials | Your disk, never transmitted |
| LLM calls | Direct from your container to the provider you configure |
What leaves your infrastructure
Being precise about this matters more than anything else on this page:
- LLM requests. The agent sends schema metadata, the context you've curated in the Knowledge Base, and conversation content to whichever LLM provider you configure — using your API key, from your container. No MinusX-operated proxy sits in between. See LLM Providers.
- Telemetry — by default, crash reports only (no traces, no PII, no analytics); one environment variable (
MX_TELEMETRY=off) turns even that off. The full, honest inventory is on the Telemetry page. - Nothing else. Query results, warehouse credentials, and your documents stay on your infrastructure.
Installation
Two supported paths — both are covered in the installation guide:
- Installer script (recommended): pulls the prebuilt image from GitHub Container Registry, prompts for the required secrets, and starts the container.
- From source: clone the repo and
docker compose up— builds the image locally.
Upgrades & data persistence
All state lives under the data/ directory you mount into the container (PGLite documents, DuckDB analytics, uploads). Upgrading is: pull the newer image, restart the container with the same mounts. Re-running the installer script does exactly this.
Back up the data/ directory (and your external Postgres, if you use one) — that is the entirety of MinusX's state.