Self-Hosting Overview
Run the Edgee AI Gateway on your own infrastructure — connected or air-gapped.
The AI Gateway runs on Edgee's cloud by default. You can also run it on your own infrastructure — a VM, your Kubernetes cluster, or an air-gapped network — using the same container image. This is a licensed deployment of the proprietary gateway. Configuration, telemetry, and usage enforcement depend on the deployment mode.
The image is public: ghcr.io/edgee-ai/gateway on GitHub Container Registry, anonymous pull, no registry credentials. The container listens on port 8080 and exposes a health endpoint at GET /status. It runs non-root (uid 65534) with a read-only root filesystem.
Run modes
Pick how the gateway should run before you deploy. The mode decides whether the gateway talks to Edgee at all.
Linked to Edgee. Default mode once a license key is configured. The gateway pulls its full configuration from the Edgee API on a schedule and reports telemetry. Recommended for most deployments — you manage config in the Console and the gateway keeps itself in sync.
- Enabled by default (
gateway.apiSync.enabled: true, default interval: 15 seconds) — no extra setting needed. - Requires both a license key (
LICENSE_KEY) and a signature key (EDGEE_SIGNATURE_KEY). The license identifies your org and authorizes config pulls; the signature key authenticates your API-key tokens. - Telemetry is optional and exports to your own OTLP collector.
- Usage metering is exported to Edgee at
https://onprem-logs.edgee.ai/v1/logs(authenticated with your license key) so it appears in the team dashboard. Point it at your own collector withUSAGE_OTLP_ENDPOINTif you prefer — the license-key auth is still sent by default even to a custom collector; setUSAGE_OTLP_USE_LICENSE_AUTH=falseto opt out.
Comparison
| Connected | Headless | |
|---|---|---|
gateway.apiSync.enabled | true (default) | false |
| Config source | Pulled from the Edgee API, kept in sync | Your own gateway.toml |
| Telemetry / outbound | Configuration sync and configured exports; provider requests | Provider requests; review any explicitly configured exports |
LICENSE_KEY | Required (authorizes config pulls) | Required |
EDGEE_SIGNATURE_KEY | Required | Not used |
| Best for | Most self-hosted deployments | Air-gapped or isolated networks |
Prerequisites
- Docker Compose: any recent Docker Engine with Compose v2.
- Kubernetes / Helm: Kubernetes 1.24+ and Helm 3.8+.
- Network egress to
ghcr.ioto pull the image (or mirror it into your own registry for air-gapped installs). - For connected mode, outbound access from the gateway to the Edgee API.
Where to get your keys
Both keys come from the Edgee Console. Open your organization's Org settings → On-Premise and click Reveal deployment secrets. This is available to org admins on on-premise organizations.
- License key →
LICENSE_KEY - Signature key →
EDGEE_SIGNATURE_KEY(connected mode only)
Treat both as secrets. Keep them out of version control — inject them through environment variables, a .env file, or a Kubernetes Secret.
Configuration reference
In headless mode you author a gateway.toml. See Headless configuration for the file structure, credentials, and verification steps.