> ## 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. Compression, routing, and observability work the same way; you control where the gateway runs and what it can reach.

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.

<Tabs>
  <Tab title="Connected">
    Linked to Edgee. 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.

    * Set `gateway.apiSync.enabled: true` (default interval: 15 seconds).
    * 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.
  </Tab>

  <Tab title="Headless">
    Air-gapped. No config fetch, no telemetry, no outbound calls. 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`.
    * 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.
  </Tab>
</Tabs>

### Comparison

|                           | Connected                                | Headless                        |
| ------------------------- | ---------------------------------------- | ------------------------------- |
| `gateway.apiSync.enabled` | `true`                                   | `false`                         |
| Config source             | Pulled from the Edgee API, kept in sync  | Your own `gateway.toml`         |
| Telemetry / outbound      | Reports telemetry (optional OTLP export) | None — fully air-gapped         |
| `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`. The full config schema — including the three compression strategies (`tool_result_trimming`, `tool_surface_reduction`, `output_brevity`) and routing — lives in the open-source repo: [`edgee-ai/edgee`](https://github.com/edgee-ai/edgee).

## Next steps

<CardGroup cols={2}>
  <Card title="Docker Compose" icon="container" href="/self-hosting/docker-compose">
    Run the gateway with Docker Compose, in either mode.
  </Card>

  <Card title="Kubernetes & Helm" icon="ship" href="/self-hosting/kubernetes-helm">
    Install the public Helm chart on your cluster.
  </Card>
</CardGroup>