Environment

What this is for

The gateway is configured entirely through environment variables. The Register Gateway dialog on 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.

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.

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.

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

Deploy — minimum env vars from the Register Gateway dialog.
Activate — what success looks like once the gateway boots.
Settings → Traffic — org-wide rate-limit and cache settings that override the gateway-local defaults above.

Getting Started

Platform

Gateway

Discovery

Resources

API Reference

What this is for

Required: cloud registration

Production hardening

Cloud overrides

Supabase JWT validation

Server

CORS

Database

Redis

Rate limiting (gateway-local)

Cache

Semantic cache (preview)

Observability

Admin UI

API key prefix

​What this is for

​Required: cloud registration

​Production hardening

​Cloud overrides

​Supabase JWT validation

​Server

​CORS

​Database

​Redis

​Rate limiting (gateway-local)

​Cache

​Semantic cache (preview)

​Observability

​Admin UI

​API key prefix

​Related

What this is for

Required: cloud registration

Production hardening

Cloud overrides

Supabase JWT validation

Server

CORS

Database

Redis

Rate limiting (gateway-local)

Cache

Semantic cache (preview)

Observability

Admin UI

API key prefix

Related