Deployment Security
In what cases should a team self-host?
Self-hosting Onyx keeps all data inside your own infrastructure. You control data processing, storage, and network access. Teams with the highest security requirements often self-host. Self-hosting needs more operational work than Onyx Cloud, so we recommend Cloud unless you need to self-host. The Community edition is free to self-host. The Business and Enterprise plans are also available self-hosted. You subscribe from the admin panel, and Onyx issues a license to your instance. See Plans & Billing.Can I run Onyx completely offline in an air-gapped fashion?
Yes. You must also host your own LLM for Onyx to connect to. Use a large LLM instead of a quantized or light version of a major model. For an air-gapped deployment:- Set
ONYX_AIRGAPPED=trueso Onyx does not fetch model catalogs or release notes from GitHub. - Set
DISABLE_TELEMETRY=trueto stop fleet telemetry. - Upload a Business or Enterprise license file manually. See Plans & Billing.
- Use
onyx-cli deploy upgrade --offlineto move to a staged version. See Onyx CLI.
How do I keep my Onyx deployment up to date or get security patches?
Onyx releases are backwards compatible. An upgrade rarely needs manual steps beyond a redeploy, and database migrations run automatically on start. See Release Process & Updates and the Deployment section.Is it possible to configure monitoring for self-hosted Onyx?
Yes. Onyx exposes Prometheus metrics:- The API server and the MCP server serve
GET /metrics. SetMETRICS_AUTH_TOKENand scrape with a bearer token. Without a token, every request gets a401. - Each background worker serves metrics on its own port inside the cluster network.
- The Helm chart ships
ServiceMonitorresources (monitoring.serviceMonitors.enabled) and Grafana dashboards (monitoring.grafana.dashboards.enabled).
Can I send security events to my SIEM?
Yes. Onyx writes an audit-event stream as JSON log lines for logins, user and permission changes, admin configuration changes, and credential access. Point your log shipper at the Onyx logs. See Audit Logs & SIEM Integration.Does Onyx send any data to the Onyx team?
Self-hosted Onyx sends anonymous fleet telemetry by default. It never sends names, URLs, email addresses, user IDs, document content, or query text. SetDISABLE_TELEMETRY=true on every service to turn it off.
See Data Processing.