Get started

Run it in a container in a few minutes.

Run it with docker compose, from source, or on Kubernetes with the Helm chart. Configuration lives in environment variables, so there is no config file to version. Locally, a built-in development issuer stands in for your identity provider; in production, point it at the real one over OIDC.

Install

Three ways in.

Local, with docker compose

# generate three keys first
openssl rand -hex 32   # ENCRYPTION_KEY, SESSION_KEY, AUDIT_CHECKPOINT_KEY
# set ADMIN_EMAIL / ADMIN_PASSWORD, plus OIDC_* (or AUTH_MODE=local)
docker compose up -d
# log in at http://localhost:8080

Or from source

make web-install && make web-build   # build the embedded web UI once
make build                           # bin/gateway, needs web/dist
go run ./cmd/gateway                 # or make run

Or on a cluster, with the Helm chart

helm install go-agentic-gateway deploy/helm/go-agentic-gateway \
  -n agentic-gateway --create-namespace -f deploy/helm/custom.yaml

AUTH_MODE defaults to oidc, and in that mode the binary refuses to boot without OIDC_ISSUER and OIDC_AUDIENCE. Set it to local to run the built-in local issuer instead. The Helm chart refuses to render while secrets still carry CHANGE_ME, and --dry-run previews the release before anything deploys.

Connecting agents

Browser clients and headless agents.

In oidc mode, an unauthenticated request gets a 401 response pointing to the gateway's protected-resource metadata (RFC 9728), which names your identity provider and lists the scopes the MCP server's rules require. OAuth-capable clients then complete a standard authorization-code flow with PKCE against your IdP.

Headless agents cannot click through a login. Mint personal access tokens for them in the web UI, the admin API, or with gwctl. The token is displayed once and stored only as a hash, and each onboarding bundle includes the agent's scopes and a ready-to-paste connection snippet. A token never outscopes its agent: the scopes are pinned at mint time, and if you narrow the agent later, a stale token is refused on its next request.

Configuration

The environment is the config.

The variables below cover most deployments; the full reference lives in .env.example.

AUTH_MODE

oidc (default) or local. In oidc mode the gateway refuses to start without an issuer and an audience; agent tokens work in both modes.

DATABASE_URL

PostgreSQL 18 or newer is the only database. Configuration, rate-limit counters, sessions, and the audit log all live there, so several replicas can share the work.

ENCRYPTION_KEY

Encrypts upstream credentials and audit payloads at rest with AES-256-GCM. Required, and not rotatable, so back it up with the database.

LLM_PROXY_ENABLED

The LLM endpoints are off by default. Set true to mount /llm/{slug}/v1.

GATEWAY_MODE

all (default), control, data-mcp, or data-llm, if you want to run administration and request handling as separate processes.

AUDIT_PAYLOAD

Store arguments and resource bodies in audit events. DLP applies before anything is written.

Clone and read

git clone https://git.parzival.link/r5i.xyz/go-agentic-gateway
# docs/ holds the manuals and the design documents

Docker compose up, then point an agent at it.

Clone the repository ↗ Back to overview