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