Agent Deployment Guide

These scripts are automatically configured for wg0 on network unsaved.

Part 1: Initial Node Provisioning (One-time)

Step 1: Prepare Node & Generate Keys

Ensure WireGuard tools are installed on your server, then create a dedicated folder to store your keys and configuration.

Install & Create Workspace (Ubuntu/Debian)
sudo apt update && sudo apt install wireguard jq -y
mkdir -p wg0 && cd wg0
Generate Keys

Generate your WireGuard keypair. Do not share your private key.

wg genkey | tee privatekey | wg pubkey > publickey
chmod 600 privatekey
cat publickey

Step 2: Deploy Agent Scripts

These files define how the agent behaves and connects to the network. They are identical for every node in your network. You can safely automate deploying these files to all your servers.

Script Version: 1.5 • Updated June 28, 2026

This command will generate the following files in your current directory:

  • wgcp.env: Stores your Network ID and Control Plane URL.
  • sync.sh: The core logic that applies WireGuard changes without dropping active connections.
  • agent-stream.sh: The background agent that listens for real-time updates.
  • download_config.sh: An optional helper to manually fetch the latest configuration.

Step 3: Connect to Control Plane

Run the streaming agent. It connects to the Control Plane, applies your initial configuration, and stays connected to apply live updates instantly.

sudo ./agent-stream.sh

Tip: Use tmux or setup a systemd service to keep this running in the background.

Alternative: Manual Configuration (Windows / Mac / Manual Linux)

If you don't want a background process, or are using a non-Linux client, you can use the generated configuration directly.

1. Download Target Configuration
./download_config.sh
2. Execute Sync (Linux Only)
sudo ./sync.sh
Part 2: Operations & Background Service

Step 4: Operations & Service Setup

Useful commands to manage your local WireGuard interface and run the agent in the background.

Verify Connection Status

View active peers, endpoints, and data transfer.

sudo wg show wg0
Bring Interface Down / Up

Disconnect from or manually reconnect to the network.

sudo wg-quick down wg0
sudo wg-quick up wg0
Run Agent as a Background Service (systemd)

To keep the streaming agent running permanently, create a service file at /etc/systemd/system/wgcp-agent.service:

/etc/systemd/system/wgcp-agent.service
[Unit]
Description=WG-CP Streaming Agent
After=network.target

[Service]
Type=simple
# Update this path to where you created your workspace
WorkingDirectory=/root/wg0
ExecStart=/bin/bash /root/wg0/agent-stream.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Service Commands:

  • Start & Enable on boot: sudo systemctl enable --now wgcp-agent
  • Check status: sudo systemctl status wgcp-agent
  • Restart (e.g., after script updates): sudo systemctl restart wgcp-agent
  • View live logs: sudo journalctl -u wgcp-agent -f
  • Stop & Disable: sudo systemctl disable --now wgcp-agent
Part 3: Name Resolution (Automated or Manual)

Option A: Automated DNS (CoreDNS)

The WG-CP agent can automatically manage a local CoreDNS instance. This provides seamless name resolution (e.g., server-01.vpn) for all nodes on the network without interfering with your host's primary DNS.

How to Enable

Simply add host_dns: true to a node in your YAML configuration. The streaming agent will automatically download CoreDNS and start serving records.

Option B: Manual Hosts File

If you prefer not to run a DNS server, you can manually download a /etc/hosts compatible file.

1. Download Hosts File
curl -s "https://w1.wgcp.dev/api/v1/networks/YOUR_NETWORK_ID/hosts" > /etc/wg0.hosts
2. Enable in DNS (dnsmasq)
echo "addn-hosts=/etc/wg0.hosts" | sudo tee /etc/dnsmasq.d/wg0.conf
sudo systemctl restart dnsmasq