Managing Peers

How to create, list, and delete WireGuard peers using Wiretastix.

WireGuard peers are the clients that connect to your Wiretastix VPN server. This guide will show you how to manage these peers using the wiretastix-cli’s peer command group.

Before proceeding, ensure your Wiretastix daemon is running and you are connected with the CLI as described in Creating an API Token and Connecting with the CLI.

1. Create a New M2M Peer

The peer create command creates an unmanaged peer: one with no associated user and no tie to OIDC authentication at all – the CLI’s own help text calls it “create anonymous peer”. This is not how regular users get their VPN access; end users authenticate through your OIDC Identity Provider and get their peer provisioned automatically as part of that self-service flow (see OIDC Integration).

The main use case for peer create is machine-to-machine tunnels: servers, backup targets, IoT devices, or site-to-site links where there’s no human logging in to authenticate. You need to provide a name for the peer:

wiretastix-cli
> peer create backup-server

The name must be 1-16 characters: letters, digits, spaces, ., _, and -. Leading/trailing whitespace is trimmed automatically before it’s checked and stored, so a name of nothing but spaces is rejected rather than silently accepted.

Names aren’t unique. There’s no duplicate-name check – peer create backup-server twice gives you two distinct peers both named backup-server. A peer’s name is just a human-friendly label; id and public_key are what actually identify it (use peer list to tell same-named peers apart).

The client configuration is only ever shown once, right here, at creation time – there is no separate command or API endpoint to retrieve it again later. The command prints it as a scannable QR code and as raw WireGuard config text in the same response. Save it immediately; if you lose it, the only way to get a peer connected again is to delete it and create a new one.

Example output:

[Interface]
PrivateKey = <client_private_key>
Address = 10.0.0.2/32, fd00::2/128
DNS = 1.1.1.1, 8.8.8.8
MTU = 1420

[Peer]
PublicKey = <server_public_key>
PresharedKey = <preshared_key>
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = your_server_ip:51820
PersistentKeepalive = 25

There is no way to associate a peer with a user through this command, the underlying REST API, or any other API call – peer create and its POST /peers/ endpoint only ever create unmanaged peers. The only way a peer gets created with a user association is through that user’s own OIDC self-service login flow (see OIDC Integration).

Unmanaged peers are isolated from self-service users. A peer with no owning user can only be renamed or deleted through the CLI/API (by an administrator) – no self-service end user can touch it through the web UI’s rename/delete actions, regardless of that peer’s numeric ID. Only a peer’s own owning user (or an admin) can manage it through self-service.

2. List All Peers

To see a list of all configured peers, use the peer list command:

> peer list

This displays a table with each peer’s ID, public key, associated user (if any), peer name, assigned IPv4/IPv6 addresses, and whether it’s active. You’ll need a peer’s numeric ID from this table (not its name) to delete it.

3. Get Peer Status

To view the real-time status of connected peers, including their latest handshake and data transfer statistics, use the peer status command:

> peer status

This command provides insights into active connections and data usage.

4. Delete a Peer

To remove a peer, use the peer delete command followed by its numeric ID (from peer list) – not its name:

> peer delete 42

You can delete several peers in one call by passing multiple IDs:

> peer delete 42 43 44

Deleting a peer will remove its configuration from Wiretastix and from the WireGuard interface, effectively disconnecting the client.

Next Steps

With peers configured, you might want to organize them using Users and Groups, or define specific Network Rules.