Telegram bot for managing WireGuard VPN.
- Add new clients with automatic configuration and QR code generation.
- Manage clients: delete, disable, enable.
- View client status (endpoint, traffic, etc.).
- Register an unlimited number of servers.
-
Before installation, create an account for your bot using BotFather. You can read more about BotFather here.
-
Also, you need to know your chat ID. You can find it out using special bots, for example, userinfobot.
-
And, of course, you should already have WireGuard deployed on your server. It's recommended to add names to peers for convenience, as shown in the example, if you are using the default WireGuard:
... # Walter [Peer] PublicKey = <publickey> AllowedIPs = 10.0.0.2/32 # Jesse [Peer] PublicKey = <publickey> AllowedIPs = 10.0.0.3/32 ...If you are using AmneziaWG, the name should already be in the
#_Nameattribute:... [Peer] #_Name = Rick #_GenKeyTime = 2025-03-29T01:29:06.021250 #_PrivateKey = <privatekey> PublicKey = <publickey> AllowedIPs = 10.9.9.2/32 [Peer] #_Name = Daryl #_GenKeyTime = 2025-03-29T01:30:06.036150 #_PrivateKey = <privatekey> PublicKey = <publickey> AllowedIPs = 10.9.9.3/32 ...
- Install Docker.
- Clone the repository and go to the directory with it:
git clone https://github.com/subs1stem/wg-assistant.git cd wg-assistant - Copy and edit the .env file:
cp .env.example .env nano .env
- Copy and edit the servers configuration file:
cp servers.example.json servers.json nano servers.json
Important
If you don't want to use an SSH connection to the Linux host at this stage, go here.
Important
To use the bot with RouterOS, make sure the port for the API is enabled on your device.
💡 Full description of the parameters used in the server configuration file.
[
// Parameters of one server are a JSON record.
// Parameters that have a default value can be omitted.
{
// Ensure that different names are used for different servers, or you will get an error.
"name": "Any name",
// "Linux" for Linux-based servers or "RouterOS" for MikroTik-based servers.
// Defaults to "Linux".
"type": "Linux",
// "WireGuard" or "AmneziaWG" depending on the protocol being used.
// Defaults to "WireGuard".
"protocol": "WireGuard",
// Path to the WireGuard server configuration file.
// Defaults to "/etc/wireguard/wg0.conf" for "WireGuard" protocol.
// Defaults to "/etc/amnezia/amneziawg/awg0.conf" for "AmneziaWG" protocol.
"path_to_config": "/etc/wireguard/wg0.conf",
// Interface name for the WireGuard server.
// Defaults to "wg0" for "WireGuard" protocol.
// Defaults to "awg0" for "AmneziaWG" protocol.
"interface_name": "wg0",
// Endpoint for peers as an IP address or domain name.
// By default, the host's external IP address will be used.
"endpoint": "myserver.com",
// DNS addresses for peers. Can be a single address or a comma-separated list.
// By default, the internal address of the server interface will be used.
"dns": "1.1.1.1, 1.0.0.1",
// The IP address or domain name of the WireGuard host that the bot will use to connect.
// If not specified, a local client will be used.
"server": "192.168.32.1",
// The port of the WireGuard host that the bot will use to connect.
// Defaults to 22 (SSH) for "Linux" type.
// Defaults to 8728 (RouterOS API) for "RouterOS" type.
"port": 22,
// Username that the bot will use to connect. Defaults to the current local username.
"username": "root",
// Password that the bot will use to connect. Also used for private key decryption.
// If not specified, private key will be used.
"password": "toor",
// The filename, or list of filenames, of optional private key(s)
// and/or certs to try for authentication.
// If not specified, the bot will try to use local keyfiles or the SSH agent.
"key_filename": "/home/user/.ssh/id_ed25519"
},
// JSON record for next server.
{
// ...
// ...
// ...
}
]-
Create an image of your bot:
sudo docker build -t subs1stem/wg-assistant . -
Run a container with your image:
sudo docker run --name wg-assistant --restart unless-stopped \ -v ~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro \ -d subs1stem/wg-assistant💡 Optionally, mount the bot's configuration files into the container:
sudo docker run --name wg-assistant --restart unless-stopped \ -v ~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro \ -v ./servers.json:/app/servers.json:ro \ -v ./.env:/app/.env:ro \ -d subs1stem/wg-assistantOr just run the container without SSH key and mounting configurations:
sudo docker run --name wg-assistant --restart unless-stopped -d subs1stem/wg-assistant
If you want to deploy the bot on the same host as the WireGuard server and avoid using SSH, you can do it without
the servers.json configuration file, or simplify the configuration by specifying only the name parameter:
[
{
"name": "My WireGuard"
}
]or for AmneziaWG:
[
{
"name": "My AmneziaWG",
"protocol": "AmneziaWG"
}
]After that, you need to build the image with the argument LOCAL_DEPLOYMENT_WG=true or LOCAL_DEPLOYMENT_AWG=true
depending on the protocol you are using. This will install the necessary utilities inside the container.
For WireGuard:
sudo docker build --build-arg LOCAL_DEPLOYMENT_WG=true -t subs1stem/wg-assistant .For AmneziaWG:
sudo docker build --build-arg LOCAL_DEPLOYMENT_AWG=true -t subs1stem/wg-assistant .Or use both arguments if you have both VPNs on your server:
sudo docker build --build-arg LOCAL_DEPLOYMENT_WG=true --build-arg LOCAL_DEPLOYMENT_AWG=true -t subs1stem/wg-assistant .Finally, run the container with the server configuration directories mounted.
For WireGuard:
sudo docker run --name wg-assistant \
--restart unless-stopped \
--cap-add NET_ADMIN \
--network host \
-v /etc/wireguard:/etc/wireguard \
-d subs1stem/wg-assistantFor AmneziaWG:
sudo docker run --name wg-assistant \
--restart unless-stopped \
--cap-add NET_ADMIN \
--network host \
-v /etc/amnezia/amneziawg:/etc/amnezia/amneziawg \
-d subs1stem/wg-assistantFor both:
sudo docker run --name wg-assistant \
--restart unless-stopped \
--cap-add NET_ADMIN \
--network host \
-v /etc/wireguard:/etc/wireguard \
-v /etc/amnezia/amneziawg:/etc/amnezia/amneziawg \
-d subs1stem/wg-assistant