Skip to content

Client Configs & QR Codes

Create complete WireGuard client profiles and render them as QR codes.

generateClientConfig

generateClientConfig(options: {
  privateKey: string
  clientAddress: string | string[]
  serverPublicKey: string
  serverEndpoint: string
  allowedIPs?: string | string[]
  dns?: string | string[]
  persistentKeepalive?: number
  presharedKey?: string
  mtu?: string | number
  extraInterface?: Record<string, WireGuardValue>
  extraPeer?: Record<string, WireGuardValue>
}): string
import { generateClientConfig } from "@kriper0nind/wg-utils"
 
const config = generateClientConfig({
  privateKey: clientPrivateKey,
  clientAddress: "10.0.0.2/32",
  serverPublicKey,
  serverEndpoint: "vpn.example.com:51820",
  allowedIPs: ["0.0.0.0/0", "::/0"],
  dns: ["1.1.1.1", "8.8.8.8"],
  persistentKeepalive: 25,
})

Defaults:

  • allowedIPs defaults to ["0.0.0.0/0", "::/0"].
  • serverEndpoint must be non-empty.
  • privateKey, serverPublicKey, and an optional presharedKey must be valid WireGuard key strings.
  • extraInterface and extraPeer are assigned after the standard fields and can add or override fields.

End-to-end client provisioning

import {
  addPeer,
  generateClientConfig,
  generateClientQRCode,
  generateKeys,
  getPubKey,
} from "@kriper0nind/wg-utils"
 
const clientKeys = await generateKeys()
const peer = await addPeer("/etc/wireguard/wg0.conf", {
  publicKey: clientKeys.publicKey,
  persistentKeepalive: 25,
})
 
const { publicKey: serverPublicKey } = await getPubKey("/etc/wireguard/wg0.conf")
 
const clientConfig = generateClientConfig({
  privateKey: clientKeys.privateKey,
  clientAddress: peer.address,
  serverPublicKey,
  serverEndpoint: "vpn.example.com:51820",
  persistentKeepalive: 25,
})
 
await generateClientQRCode(clientConfig, {
  outputPath: `/tmp/${peer.ip}.png`,
})

generateClientQRCode

generateClientQRCode(
  config: string | WireGuardConfig | GenerateClientConfigOptions,
  options?: {
    outputPath?: string
    type?: "data-url" | "terminal"
    width?: number
  },
): Promise<string>

The function accepts:

  • WireGuard configuration text
  • A WireGuardConfig object
  • GenerateClientConfigOptions, which are converted with generateClientConfig() first

Return a PNG data URL

import { generateClientQRCode } from "@kriper0nind/wg-utils"
 
const dataUrl = await generateClientQRCode(clientConfig)

Default width is 512 pixels and the error correction level is M.

Write a PNG file

const filepath = await generateClientQRCode(clientConfig, {
  outputPath: "/tmp/client.png",
  width: 768,
})

The parent directory is created when necessary and the PNG is written with mode 0600.

Render in a terminal

const terminalQr = await generateClientQRCode(clientConfig, {
  type: "terminal",
})
 
console.log(terminalQr)

Security

Client configurations contain private keys. Treat generated config text, PNG files, QR codes, and data URLs as secrets.