Set Up a WireGuard Client

3. Managing peers / clients

The Peers & Clients page is split in two:

Home Gateways — at the top, as expandable cards with telemetry.
Peers / Clients — at the bottom, as a table with search, group filter and tag filter. Gateway peers are filtered out of this table so you don't see them twice.

3.1 Create a new peer

Open the + Add dialog. The most important fields:

Name — unique, 1–63 characters, a-z/0-9/hyphen. Also used as the WireGuard peer label.
Description — free, max. 255 characters. For example, the client-version label from the GateControl desktop client is automatically stored here.
Internal hostname (Pro) — see Domains & DNS. Only if you use Internal-DNS.
Group — optional, see 3.4 Groups.
Tags — comma-separated; e.g. server, production, nas.
DNS server (override) — overrides the global DNS entry only for this peer. If the field is empty, the global value from Settings applies.
Expiration date — after this date the peer is automatically disabled (background job every 60 seconds).
Home Gateway (checkbox) — turns the peer into a gateway (see 4. Home-Gateway). Cannot be changed afterwards.

After Create you get config, QR code and — for gateways — additionally the gateway.env as a one-time display.

3.2 Set hostname (Internal DNS)

In the peer table a small badge appears in each peer row: manual (set by the admin), auto (reported by the agent) or stale (not yet re-reported after master-key rotation).

Sticky-admin rule: If you as admin have set the hostname, no agent heartbeat will overwrite this value. If you want automatic adoption again, delete the hostname in the peer modal — then the next agent heartbeat may set it again.

You can override agent-set names at any time as admin. The flag then flips to manual and stays there.

3.3 Tags

Tags are free, non-hierarchical labels. You can manage them under Settings → Tags. There you have a registry — tags you've created can already be autocompleted. A tag that is attached to peers but is not in the registry shows the badge not registered.

Usage:

In the peer table you can filter by tag (chip bar above the table).
In the peer modal you enter tags comma-separated.
On save, unknown tags are automatically added to the registry so they show up in autocomplete in the future.

3.4 Groups

Peer groups are visible categories with name, color and description (e.g. "Office", "Family", "Servers"). Each peer belongs to exactly one or no group.

Create and maintain groups: Settings → Peer Groups
Assign peer: in the peer dialog dropdown Group
Filter: on the Peers page in the dropdown All / Ungrouped / <Group>

3.5 Disable vs. delete

Disable (toggle in the peer row, or batch action):
- Peer stays in the DB, keys are preserved.
- WireGuard config is rewritten without this peer, the active connection is disconnected immediately.
- Can be re-enabled at any time.
Delete (trash icon, with confirmation):
- Peer is permanently removed, keys are gone.
- Routes belonging to this peer show a peer offline badge — active connections are disconnected.
- Cannot be undone. If you recreate the peer, it gets a new IP and new keys.

3.6 Expiration dates

In the peer dialog under Expiration date you can choose 1d / 7d / 30d / 90d or a custom date. After expiry the peer is automatically disabled. In the table you see:

Expiring soon (yellow badge, < 7 days)
Expired (red badge, already disabled)

3.7 Batch actions

Top right on Select, then checkboxes in the rows. At the bottom an action bar appears with Enable, Disable, Delete.