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

# Environment

> Every environment variable the Guardway gateway container reads, grouped by purpose. Pair with the Register Gateway dialog on Deploy.

## What this is for

The gateway is configured entirely through environment variables. The Register Gateway dialog on [Deploy](/guardway-gateway/deploy) generates the **minimum** set you need (registration token, gateway name, optional LAN IP). This page is the **full** reference for every other variable the container accepts — production hardening, control-plane overrides, Supabase JWT validation, database/Redis, and observability.

All variables are read once on startup. To change a value, edit `.env` (or your config-management equivalent) and restart the container.

## Required: cloud registration

Every gateway you register from the dashboard runs in cloud mode and exchanges a one-time token for long-lived credentials.

| Variable                      | Default   | Purpose                                                                                                                                                                  |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GUARDWAY_CLOUD_ENABLED`      | `false`   | Master switch. The bundle from the Register Gateway dialog sets this to `true`. When `false` the gateway runs fully self-contained and never contacts the control plane. |
| `GUARDWAY_REGISTRATION_TOKEN` | —         | One-time pairing token from the dashboard. Used **once**, on first boot, to exchange for long-lived credentials. Single-use; lives \~1 hour.                             |
| `GUARDWAY_GATEWAY_NAME`       | `default` | Display label for this gateway in the dashboard. Edit later from the gateway detail page.                                                                                |

After the first successful registration the token is ignored — credentials are loaded from disk on every subsequent boot. See [Deploy → Step 4](/guardway-gateway/deploy#step-4-registration-handshake).

## Production hardening

Recommended in production. The defaults are placeholder values that work for local development only — the gateway refuses to boot in any non-`development` environment if `ENCRYPTION_KEY` is left at its default or shorter than 32 characters.

| Variable                 | Default           | Purpose                                                                                                                                   |
| ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `JWT_SECRET`             | dev placeholder   | Signs gateway-issued JWTs. Replace with a long random string in production.                                                               |
| `ENCRYPTION_KEY`         | dev placeholder   | Encrypts provider secrets and other at-rest values. **Must be ≥ 32 characters in non-development environments**, otherwise startup fails. |
| `MASTER_KEY`             | dev placeholder   | Master API key prefix used for emergency access. Rotate from the dashboard when possible.                                                 |
| `JWT_MAX_TTL`            | `2160h` (90 days) | Hard cap on any dashboard JWT lifetime.                                                                                                   |
| `JWT_MANUAL_SESSION_TTL` | `2160h` (90 days) | Lifetime when the user picks **manual** session retention, before being clamped by `JWT_MAX_TTL`.                                         |
| `JWT_CREDENTIAL_MAX_TTL` | unset             | Optional tighter cap on password-login JWTs. Master-key sessions are not limited by this value.                                           |

## Cloud overrides

The defaults already point at Guardway Cloud. Change these only for staging, an internal control plane, custom credential storage, or interval tuning.

| Variable                       | Default                          | Purpose                                                                                                                                                                       |
| ------------------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GUARDWAY_CLOUD_URL`           | the Guardway control plane URL   | Overrides the control-plane endpoint the gateway reaches on registration, heartbeat, and config sync.                                                                         |
| `GUARDWAY_LOGS_URL`            | the Guardway logs ingestion URL  | Overrides the logs ingestion endpoint.                                                                                                                                        |
| `GUARDWAY_CREDENTIALS_PATH`    | `/etc/guardway/credentials.json` | Where the gateway persists long-lived credentials after the first registration. Mount a writable volume at this path or override to a directory the container user can write. |
| `GUARDWAY_HEARTBEAT_INTERVAL`  | `60s`                            | How often the gateway pings the control plane. The dashboard flips a gateway from **Online** to **Offline** after roughly 3× this interval without a heartbeat.               |
| `GUARDWAY_EVENT_PUSH_INTERVAL` | `10s`                            | How often buffered platform events (counts, latencies — never raw prompts or completions) are pushed to the control plane.                                                    |
| `GUARDWAY_LOCAL_IP`            | empty                            | LAN/host IP advertised in heartbeats so the dashboard can offer a same-network direct-connect URL. Optional but recommended.                                                  |

<Note>
  Request bodies, prompts, and completions **never** leave the gateway host. Only aggregate event metadata (counts, latencies, costs) and administrative audit events are pushed to the control plane.
</Note>

## Supabase JWT validation

Set these when the gateway should accept dashboard Supabase JWTs directly (Phase 3.1 — used by direct-connect flows). Both must be set together.

| Variable                     | Default | Purpose                                                                         |
| ---------------------------- | ------- | ------------------------------------------------------------------------------- |
| `GUARDWAY_SUPABASE_JWKS_URL` | empty   | URL of the Supabase project's JWKS endpoint (`/auth/v1/.well-known/jwks.json`). |
| `GUARDWAY_SUPABASE_ISSUER`   | empty   | Expected `iss` claim — the Supabase project's `/auth/v1` URL.                   |

When `GUARDWAY_SUPABASE_JWKS_URL` is empty the gateway only validates locally-issued JWTs.

## Server

| Variable             | Default       | Purpose                                                                                                                |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `PORT`               | `8080`        | HTTP API listen port.                                                                                                  |
| `HOST`               | `0.0.0.0`     | Bind address.                                                                                                          |
| `ENVIRONMENT`        | `development` | Mode: `development`, `production`, `test`. Triggers the `ENCRYPTION_KEY` validation above when not `development`.      |
| `HTTP_READ_TIMEOUT`  | `15s`         | Request read timeout.                                                                                                  |
| `HTTP_WRITE_TIMEOUT` | `5m`          | Response write timeout (long enough for streaming completions).                                                        |
| `HTTP_IDLE_TIMEOUT`  | `60s`         | Keep-alive idle timeout.                                                                                               |
| `TRUSTED_PROXIES`    | empty         | Comma-separated CIDRs of proxy IPs whose `X-Forwarded-For` headers the gateway should trust. Empty uses safe defaults. |

## CORS

| Variable               | Default                       |
| ---------------------- | ----------------------------- |
| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000`       |
| `CORS_ALLOWED_METHODS` | `GET,POST,PUT,DELETE,OPTIONS` |
| `CORS_ALLOWED_HEADERS` | `Content-Type,Authorization`  |

All three accept comma-separated lists.

## Database

The gateway ships with sensible defaults for the bundled Compose Postgres. Override only when pointing at an external database.

| Variable      | Default                                       |
| ------------- | --------------------------------------------- |
| `DB_DRIVER`   | `postgres`                                    |
| `DB_HOST`     | `localhost`                                   |
| `DB_PORT`     | `5432`                                        |
| `DB_USER`     | `gateway`                                     |
| `DB_PASSWORD` | `gateway`                                     |
| `DB_NAME`     | `gateway`                                     |
| `DB_SSLMODE`  | `disable`                                     |
| `DB_PATH`     | `./gateway.db` (only when `DB_DRIVER=sqlite`) |

## Redis

| Variable        | Default                  | Purpose                                           |
| --------------- | ------------------------ | ------------------------------------------------- |
| `REDIS_ENABLED` | `false`                  | Turns on Redis-backed cache and rate-limit state. |
| `REDIS_URL`     | `redis://localhost:6379` | Redis connection URL.                             |

## Rate limiting (gateway-local)

These set the **local** request and token caps the gateway enforces. Org-wide caps are configured from [Settings → Traffic](/platform/settings/traffic) and override these at runtime.

| Variable                         | Default  |
| -------------------------------- | -------- |
| `RATE_LIMIT_ENABLED`             | `true`   |
| `RATE_LIMIT_REQUESTS_PER_MINUTE` | `100`    |
| `RATE_LIMIT_TOKENS_PER_MINUTE`   | `100000` |

## Cache

These are gateway-local cache defaults. Org-wide cache settings configured from [Settings → Traffic](/platform/settings/traffic) override these at runtime.

| Variable        | Default  | Purpose                                              |
| --------------- | -------- | ---------------------------------------------------- |
| `CACHE_ENABLED` | `true`   | Master switch.                                       |
| `CACHE_TYPE`    | `memory` | `memory` or `redis` (requires `REDIS_ENABLED=true`). |
| `CACHE_TTL`     | `3600s`  | Default entry TTL.                                   |

### Semantic cache (preview)

| Variable                              | Default                  |
| ------------------------------------- | ------------------------ |
| `SEMANTIC_CACHE_ENABLED`              | `false`                  |
| `SEMANTIC_CACHE_SIMILARITY_THRESHOLD` | `0.9`                    |
| `SEMANTIC_CACHE_EMBEDDING_MODEL`      | `text-embedding-ada-002` |
| `SEMANTIC_CACHE_TTL`                  | `3600s`                  |

## Observability

| Variable             | Default                 | Purpose                                                              |
| -------------------- | ----------------------- | -------------------------------------------------------------------- |
| `PROMETHEUS_ENABLED` | `true`                  | Exposes `/metrics` for Prometheus scraping on the same port.         |
| `OTEL_ENABLED`       | `false`                 | Enables OpenTelemetry traces.                                        |
| `OTEL_ENDPOINT`      | `http://localhost:4318` | OTLP/HTTP collector endpoint.                                        |
| `JAEGER_ENDPOINT`    | empty                   | Jaeger collector endpoint. Set only when sending directly to Jaeger. |
| `TRACE_SAMPLE_RATE`  | `0.1`                   | Float between 0 and 1. Fraction of requests traced.                  |

## Admin UI

The gateway ships with a minimal local admin UI. Most users govern the gateway from the dashboard and leave this off.

| Variable           | Default |
| ------------------ | ------- |
| `ADMIN_UI_ENABLED` | `true`  |
| `ADMIN_UI_PATH`    | `./web` |

## API key prefix

| Variable         | Default | Purpose                                                                                                                                    |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `API_KEY_PREFIX` | `sk-`   | Prefix prepended to gateway-issued API keys. Change only when integrating with downstream tooling that pattern-matches a different prefix. |

## Related

* [Deploy](/guardway-gateway/deploy) — minimum env vars from the Register Gateway dialog.
* [Activate](/guardway-gateway/activate) — what success looks like once the gateway boots.
* [Settings → Traffic](/platform/settings/traffic) — org-wide rate-limit and cache settings that override the gateway-local defaults above.