Get started

Getting started

This page covers the mental model behind Wardengate and a short path from an empty cluster to a brokered SSH session. If you already have a control plane up, skip to the quickstart at the bottom.

The product in one picture

Wardengate is composed of three moving parts. The control plane is the stateful brain: policies, identities, targets, audit records. The gateway is the data plane — it terminates user protocols (SSH, RDP, database wire), evaluates policy, and proxies allowed traffic to the destination. The optional target agent runs on hosts that sit outside a routable path and dials out to the gateway.

Everything a user does is a session. Every session is bound to a named identity from your IdP, evaluated against one or more policies, and recorded for the retention window you configure.

Control plane

The control plane exposes the API and admin console, stores policy and audit state in PostgreSQL, and streams session metadata to object storage. It does not sit on the data path; a gateway outage does not impair active sessions already brokered, and a control plane outage does not take existing sessions down — it prevents new sessions from being authorized.

For production we recommend three replicas behind your load balancer, a Postgres instance you already operate, and an S3-compatible bucket with object-lock for recordings.

Gateway

Gateways are stateless. They hold short-lived config pulled from the control plane, terminate user connections, and forward only what policy allows. You can run them close to users (one per region) or close to workloads (one per VPC/VNet). Gateways authenticate to the control plane with a rotating bootstrap token and can be scaled horizontally behind a Layer-4 load balancer.

Target agent

When a target sits on an isolated network and cannot accept inbound traffic from the gateway, you install wg-agent on it or on a jumpbox in the same segment. The agent maintains an outbound QUIC tunnel to a gateway and reverses the data path: the gateway sends brokered traffic down the agent's existing tunnel instead of dialing the target itself.

Policies

A policy is a declarative record that binds one or more principals (users, groups, roles from your IdP) to one or more targets (hosts, databases, tags) under a set of constraints (protocol, account, time-of-day, MFA, approval). Policies are evaluated at connect time and re-evaluated on sensitive events within a live session.

# policy.yaml
apiVersion: wardengate/v1
kind: Policy
metadata:
  name: sre-prod-ssh
spec:
  principals:
    groups: ["sre"]
  targets:
    tags: ["env=prod"]
  protocols: ["ssh"]
  accounts: ["deploy"]
  constraints:
    mfa: required
    approval:
      required: true
      approvers: ["group:sre-leads"]
    sessionMinutes: 60
  recording:
    mode: full

Quickstart

The fastest path is the Docker quickstart, which runs the control plane and a single gateway on one machine with a local Postgres. Do not use this for anything past a proof of concept.

1. Pull and launch

docker run -d \
  --name wardengate \
  -p 443:443 -p 2222:2222 \
  -e WG_ADMIN_EMAIL=admin@example.com \
  -e WG_BOOTSTRAP_PASSWORD=change-me \
  ghcr.io/wardengate/quickstart:latest

2. Install and authenticate the CLI

curl -sSL https://get.wardengate.example/cli | sh
wgctl login --server https://localhost --insecure-skip-verify

3. Onboard your first target

wgctl target create \
  --name web-01 \
  --protocol ssh \
  --address 10.0.0.20:22 \
  --tag env=prod

4. Attach a policy and connect

wgctl policy apply -f policy.yaml
wgctl connect web-01 --as deploy

You should land in an SSH session on the target. The session shows up in the admin console under Sessions -> Active, with a live recording indicator if the policy requested one.

Where to next

Move to the installation guide for a production deployment, or the admin guide to wire up your IdP and author real policies.