Getting started

Stand up a WireGuard gateway with claimward-vpn-server, register a sign-in client, and connect a first device with the macOS, Linux or Windows app.

This walks through standing up a gateway and connecting a first device. The gateway is a Linux host; the device runs one of the three desktop apps.

1. Prepare the WireGuard gateway (Linux)

Create the wg0 interface with a server key and a listen port. Claimward manages the peers of this interface; it does not create the interface.

# /etc/wireguard/wg0.conf
[Interface]
Address = 10.80.0.1/24
ListenPort = 51820
PrivateKey = <server-private-key>

wg genkey | tee server.key | wg pubkey > server.pub
sudo wg-quick up wg0
sudo sysctl -w net.ipv4.ip_forward=1   # if you route beyond the VPN subnet

2. Run the control plane

go install github.com/claimward/claimward-vpn-server/cmd/claimward-server@v0.2.0

export AUTH_PROVIDER=github                     # the default
export GITHUB_ALLOWED_ORGS=claimward            # optional authorization (recommended)
export WG_ENDPOINT=vpn.example.com:51820
export WG_PRIVATE_KEY_FILE=/etc/wireguard/server.key
export VPN_CIDR=10.80.0.0/24
export TLS_CERT=/etc/claimward/fullchain.pem    # HTTPS, and TLS on the gRPC RouteService
export TLS_KEY=/etc/claimward/privkey.pem
export GRPC_ENDPOINT=vpn.example.com:8444       # where clients watch for route updates

sudo -E "$(go env GOPATH)/bin/claimward-server"

The server needs the rights to configure wg0 (root, or CAP_NET_ADMIN). It listens on :8443 (LISTEN_ADDR) for the enrollment API and on :8444 (GRPC_ADDR) for the RouteService. See the server reference for every variable; for experiments without a real interface, set WG_DRYRUN=true.

3. Register the sign-in client

Create a GitHub OAuth App (organisation or personal) and enable Device Flow in its settings. The apps need only its client ID, no secret. They ask for the scopes read:user, user:email and read:org.

In your identity provider, create a native/public client with PKCE and the loopback redirect http://127.0.0.1:<port>/callback. The port is picked at each sign-in, so the provider must accept any loopback port (RFC 8252). No client secret. Run the server with AUTH_PROVIDER=oidc, OIDC_ISSUER and OIDC_CLIENT_ID.

At a go-authn/bridge provider, declare two clients: the one people sign in with (device = true, wireguard_keys = true, a refresh_lifetime), and the gateway’s own client (wireguard_peers). Run the server with AUTH_PROVIDER=go-authn. See Identity providers.

4. Connect a device

Each app has a privileged helper that enrolls with the server and owns the tunnel; it is installed once, as an administrator, with the servers it may connect to. The app itself runs as you.

From a checkout of claimward-vpn-app-osx:

sudo ./scripts/install-helper.sh https://vpn.example.com   # the root LaunchDaemon
task start:bundle                                          # build Claimward.app and open it

Then fill in the server URL, the provider and its client ID in Configuration… (or in ~/Library/Application Support/Claimward/config.json), and click Connect. See the macOS app.

From a checkout of claimward-vpn-app-linux:

CGO_ENABLED=0 go build -trimpath -o bin/ ./cmd/...
sudo ./scripts/install.sh --server https://vpn.example.com

Log out and back in (the installer adds you to the claimward group), start Claimward VPN from your desktop’s menu, fill in the settings and click Connect. See the Linux app.

From a release folder built by scripts/package.sh of claimward-vpn-app-windows, in an elevated PowerShell:

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1 -Server https://vpn.example.com -Provider github -GitHubClientId Iv1.0123456789abcdef

Sign out of Windows and back in (the installer adds you to the Claimward Users group), start Claimward VPN from the Start Menu and click Connect. See the Windows app.

A person who belongs to several tenants is asked to choose one before the connection is made; see Tenants.

The device now has a tunnel interface (utunN on macOS, utun on Linux, the Wintun adapter Claimward on Windows) with its 10.80.0.x/32 address, and routes to the tenant’s networks through it.

Lease renewal comes with claimward-vpn-client v0.3.1, in the apps from v0.2.0: from then on the helper renews the lease while the tunnel is up and deregisters on Disconnect. The v0.1.0 apps do not: a connection that stays up longer than LEASE_TTL (24 hours by default) is removed from the gateway, and connecting again starts a new lease. See Leases.

Created on October 5, 2026 by tannevaled

Modified on October 5, 2026 by tannevaled

Architecture