Skip to main content
The gateway is distributed as a Docker image. You start it once with a one-time registration token from the dashboard; after that it authenticates to the cloud with long-lived credentials derived from the token.

​
Before you start

  • Docker 24.0+ with Compose v2 (see Requirements)
  • Outbound HTTPS to api.guardway.ai and to whichever LLM provider APIs you plan to use
  • An inbound port on the gateway host (default 8080) reachable from the machine running the dashboard — LAN address is fine

​
Step 1 — Generate a registration token

In the dashboard, open Gateways and click Register New Gateway. The dialog generates a token valid for 1 hour and shows you the full docker run command with the token already inlined.
Register gateway dialog
Copy the command from the dialog rather than piecing it together by hand — the token is single-use and expires in an hour.

​
Step 2 — Run the container

On the host where you want the gateway to live: 
docker run -d \
  --name guardway-gateway \
  -p 8080:8080 \
  -e GUARDWAY_REGISTRATION_TOKEN="<paste-token-from-dashboard>" \
  -e GUARDWAY_CLOUD_ENABLED=true \
  -e GUARDWAY_CLOUD_URL=https://api.guardway.ai \
  guardway/gateway:latest

​
Required environment variables

VariablePurpose
GUARDWAY_REGISTRATION_TOKENOne-time pairing token from the dashboard. Used exactly once; the gateway persists long-lived credentials after first boot.
GUARDWAY_CLOUD_ENABLEDSet to true to register the gateway with the Guardway control plane.
GUARDWAY_CLOUD_URLControl-plane URL. Default https://api.guardway.ai for SaaS customers.
See Environment for the full list of optional variables (proxy, TLS, storage backends, cache).

​
Step 3 — Verify it started

docker logs -f guardway-gateway
You should see registered with control plane followed by a heartbeat line every few seconds. The gateway is now ready for the dashboard to connect.

​
What comes next

Activate the gateway

Point the dashboard at the running gateway and confirm it’s online.

​
Production notes

For production, put a reverse proxy (nginx, Caddy, an ALB) in front of the gateway with a real certificate. The gateway itself can also terminate TLS — see Environment variables.
Mount a volume at /var/lib/guardway to persist local state (audit logs, cache, keys) across container restarts.
The image is a regular container and runs in any orchestrator. Treat GUARDWAY_REGISTRATION_TOKEN as a one-time secret; once the gateway has registered, you can remove it from subsequent manifests.