Self-hosted deployment
Run Midcore services in your own infrastructure for air-gapped networks, data residency, or compliance. You operate the API, gate runner, and evidence ledger; clients (CLI, VS Code, Desktop) point to your instance.
When to self-host
- Data must stay inside your network or region.
- You need to use your own IdP and network policies.
- Air-gapped or restricted environments.
- Custom scaling and high availability requirements.
Components
A typical self-hosted setup includes:
| Component | Role |
|---|---|
| API / gateway | Handles auth, routing, and agent/gate requests |
| Gate runner | Executes gates and writes evidence |
| Evidence ledger | Append-only store for gate results |
| Optional: database and caches | State and performance; see deployment guide |
Exact components and topology depend on the official deployment package or Helm chart. Refer to the deployment guide and release notes for your version.
Deployment checklist
- Network — TLS for all endpoints; restrict egress/ingress as required.
- Secrets — Store DB credentials, IdP client secrets, and API keys in a secret manager; never in images or Git.
- Persistence — Evidence ledger and any DB need durable storage and backups.
- Health — Configure health checks and readiness probes for API and gate runner.
Prerequisites
- Kubernetes cluster (or supported runtime per the deployment guide).
- Container registry access for Midcore images.
- Identity provider (OIDC/SAML) if you use SSO.
- TLS certificates for HTTPS.
- Resource limits and storage for logs and evidence.
Config and secrets
Configure API URL, auth, and feature flags via environment variables or a config file. Store secrets (DB credentials, IdP client secrets, API keys) in a secret manager (e.g. Kubernetes Secrets, Vault) and inject them at runtime. Never bake secrets into images or commit them to Git. See Security and Environment variables.
Production Compose and registry images
docker-compose.prod.yaml pulls three application images built by GitHub Actions (.github/workflows/build-and-push.yml): ghcr.io/<owner>/<repo>/api, .../web, and .../auth. Set GHCR_IMAGE_SLUG in your environment (e.g. GHCR_IMAGE_SLUG=myorg/maestro-midcore) so it matches the lowercase GitHub owner/repo that publishes the packages. Use IMAGE_TAG for the digest or release tag.
Docker: web frontend and API
In a Docker Compose setup, the web frontend runs as a container alongside postgres, redis, and the API. The web image is built from the app and docs in apps/web. To apply any frontend or documentation changes to the running container, rebuild the web image and restart the web (and API) services—for example:
docker compose build webthendocker compose --profile with-api up -d web api, or- Using the repo Makefile:
make docker-rebuild-web.
After rebuilding, the web container serves the latest docs and UI. Ensure the API URL and auth endpoints are set correctly for the environment (see Environment variables).
Deployment guide
Offline and BYOM add-ons
Two recurring add-ons can be activated on top of a Cloud subscription and govern what your self-hosted or hybrid deployment is entitled to do:
- Offline stack add-on — required to run the desktop IDE and self-hosted backend in offline-capable mode while keeping a Cloud subscription active. Enable it from the Billing page; entitlements sync to your tenant within a few minutes.
- BYOM add-on — lets your tenant route LLM calls through your own provider keys (OpenAI, Anthropic, Ollama, or any compatible endpoint). The CLI and Desktop pick up BYOM credentials from your tenant once the add-on is active.
Both add-ons are managed centrally in Billing and surface as feature flags on every workspace; no extra deployment step is required to switch them on once entitlements are present.