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.

Connected

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 with USAGE_OTLP_ENDPOINT if you prefer — the license-key auth is still sent by default even to a custom collector; set USAGE_OTLP_USE_LICENSE_AUTH=false to opt out.

Headless

Headless. No Edgee configuration fetch. Model requests still contact the configured provider endpoints. You author the configuration yourself and hand it to the gateway. Use this when the gateway cannot — or must not — reach the internet.

• Set gateway.apiSync.enabled: false to opt out of the default connected mode.
• You provide a gateway.toml (mounted at /etc/edgee/gateway.toml); optionally provider keys.
• Requires the license key (LICENSE_KEY) only. The signature key is not needed headless.

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.io to 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.

Next steps

Docker Compose

Run the gateway with Docker Compose, in either mode.

Kubernetes & Helm

Install the public Helm chart on your cluster.