Self-hosted setup

When to self-host

Choose self-hosted when you need the API, portal, orchestrator, database, and supporting infrastructure to run inside your own environment — for example strict data residency, private networking, or operating the full stack on your Kubernetes cluster.

Self-hosting the platform is separate from bring-your-own external models. The external_model workflow node keeps Quantlix policy, tracing, and output validation in the request path while HTTP calls go to a model you host elsewhere — without running the full Quantlix stack yourself. See Runtime Layer Extraction (BYO model).

Provider-backed deployments are another distinct path: bind a deployment to an OpenAI, Anthropic, or other provider model via an inference target. Quantlix routes /run through policy, then to the provider — no container build in your cluster. See Provider integrations.

What gets deployed

Self-hosting has two layers: the platform (Quantlix services in Kubernetes) and workload deployments (models and workflows you register through the API).

Platform stack

Production images are built and pushed for api, orchestrator, and inference, then applied via Kustomize overlays (infra/kubernetes/overlays/prod or dev for local k3d). The orchestrator patch sets the inference image your cluster uses for scheduled jobs.

Workload build path (GitHub source)

When you deploy from GitHub, the API enqueues a build task. The orchestrator worker detects build mode from the repository Dockerfile, then either:

• container_image — Kaniko builds and pushes an image; runtime_image is set to that reference.
• model_bundle — source archive is stored in MinIO; artifact_uri points at the bundle location.

On success, deployment and revision records are updated and the deployment is marked ready. On failure, tasks retry with backoff; exhausted retries land in the build dead-letter queue.

GPU inference: set gpu in deployment config. Join dedicated GPU nodes to the cluster (for example Hetzner GEX44) with the quantlix.com/gpu=true label so jobs schedule correctly. The inference image must support CUDA when running GPU workloads.

Setup steps

1. Stand up the platform

1. Provision Kubernetes (Terraform on Hetzner, an existing cluster, or local k3d per docs/API_BUILD_DEPLOY.md).
2. Build and push quantlix-api, quantlix-orchestrator, and quantlix-inference images; update the Kustomize overlay for your registry.
3. Create namespace secrets (postgres, minio, api with jwt-secret and optional billing/email keys) and apply the overlay: kubectl apply -k infra/kubernetes/overlays/prod.
4. Deploy the portal with NEXT_PUBLIC_API_URL pointing at your API (Docker self-host or external host per docs/GO_LIVE.md).
5. Verify: curl https://api.yourdomain.com/health, sign up, and confirm orchestrator and Redis pods are healthy.

2. Register workload deployments

1. Create or update a deployment via POST /deploy (portal Dashboard → Deploy or quantlix deploy). Pass deployment_id to update an existing deployment and create a new revision.
2. For GitHub-sourced deployments (source.provider == github): the API queues a build task, sets build_status to queued, and creates a DeploymentRevision. The orchestrator builds container_image (Kaniko) or model_bundle (MinIO), then writes artifact_uri, runtime_image, and related fields.
3. Wait for build_status succeeded before calling /run on GitHub deployments — the run route returns 409 while the build is incomplete.
4. Provider-backed deployments (InferenceTarget target_type provider_model) skip container builds and can reach READY without a GitHub artifact.
5. Demo models (qx-example) and MOCK_K8S environments mark deployments READY immediately; other custom container workloads may stay PENDING until the orchestrator processes the first run.
6. Revisions snapshot model_id, config, source, and artifact metadata. Rollout strategies (immediate, canary, shadow) control how config updates apply.
7. Assign deployments to projects and set registry metadata (purpose, data_classification, lifecycle_stage) as part of deploy or deployment settings.
8. Policy, contracts, redaction, and budget gates still run on every /run request before provider inference or orchestrator-scheduled inference.

For GitHub auto-redeploy: connect GitHub in the portal, configure source with owner, repo, branch, and optional auto_redeploy. Pushes that match create a new revision, update source.commit_sha, and re-queue the build worker.

What Quantlix stores vs what stays in your environment

In self-hosted mode you operate the infrastructure, but Quantlix still persists the same categories of control-plane data in your PostgreSQL (and object storage where applicable):

• Organizations, teams, projects, deployments, providers, and workflow definitions.
• Execution records, node executions, trace IDs, timing, status, and error payloads.
• Policy decisions, enforcement events, budget outcomes, and audit export metadata.
• Provider credentials encrypted before storage.

What stays in your environment: the Kubernetes cluster, inference containers built from your GitHub source, model bundles in your MinIO, and network paths between your applications and the API. Provider-backed and external_model calls still leave your boundary to reach third-party or separately hosted model endpoints — policy and traces are captured in Quantlix regardless.

Self-hosting shifts where data is stored and which network paths you control; it does not by itself guarantee a specific regulatory outcome. Map residency and subprocessors to your deployment configuration and provider choices.

Next steps

• Architecture — request lifecycle, managed vs self-hosted, and data flow.
• Provider integrations — connect OpenAI, Anthropic, Azure, and bind provider-backed inference targets.
• Runtime Layer Extraction (BYO model) — run policy and tracing around a model you host elsewhere via the external_model node.