> ## Documentation Index
> Fetch the complete documentation index at: https://www.edgee.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [tab] 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.

> [tab] 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](https://www.edgee.ai/docs/self-hosting/configuration.md) for the file structure, credentials, and verification steps.

## Next steps

> [card] [Docker Compose](https://www.edgee.ai/docs/self-hosting/docker-compose.md)
>
> Run the gateway with Docker Compose, in either mode.

> [card] [Kubernetes & Helm](https://www.edgee.ai/docs/self-hosting/kubernetes-helm.md)
>
> Install the public Helm chart on your cluster.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.