procustodibus_agent 1.8.0

Synchronizes your WireGuard settings with Pro Custodibus.

Pro Custodibus Agent

Pro Custodibus is a service that makes WireGuard networks easy to deploy and manage. You run the Pro Custodibus agent on each WireGuard host you want to manage, and the agent monitors and synchronizes the hosts' WireGuard settings with the remote Pro Custodibus service.

Installing

Requires python 3.8 or newer and libsodium. Installer script can install requirements, plus the agent itself, on most linuxes, FreeBSD, OpenBSD, and macOS (if macOS has Homebrew). Install from source like the following:

./install.sh --install

Or run it like the following to see more options:

./install.sh --help

See the Installer Documentation for full details (or to download the pre-built Windows installer).

Docker

The docker/wireguard.dockerfile is built weekly and pushed to the docker.io/procustodibus/wireguard repository. It produces a base WireGuard image without the agent.

The docker/agent.dockerfile is built weekly and pushed to the docker.io/procustodibus/agent repository. It produces a Docker image with WireGuard and the latest agent installed together.

Run either image by placing your WireGuard or Pro Custodibus configuration files in a host directory like /srv/containers/wireguard/conf, and then running the image like the following:

docker run \
    --cap-add NET_ADMIN \
    --publish 51820:51820/udp \
    --name wireguard \
    --rm \
    --volume /srv/containers/wireguard/conf:/etc/wireguard \
    procustodibus/agent

See the Container Documentation for full details.

Development

Set up dev env

Install uv, and from this project root run:

uv python install
uv sync

Dev tasks

Run unit tests:

uv run pytest

Run unit tests in watch mode:

uv run ptw .

Run unit tests with coverage report:

uv run pytest --cov --cov-report term-missing

Run linter and auto-fix where possible:

uv run ruff check --fix

Run formatter:

uv run ruff format

Build and run docker dev image (with *.conf files in /srv/containers/wireguard/conf):

docker/dev.sh dev
docker run \
    --cap-add NET_ADMIN \
    --publish 51820:51820/udp \
    --name wireguard \
    --rm \
    --volume /srv/containers/wireguard/conf:/etc/wireguard \
    procustodibus-agent:dev

Run all (docker-based) installer tests:

docker compose -f test_install/docker-compose.yml build --pull
uv run pytest test_install

Build Windows MSI

Install uv, and from this project root run:

uv run --python 3.12 --group freeze cx_freeze_setup.py bdist_msi

The MSI package will be built as dist\procustodibus_agent-x.x.x-win64.msi.

Build Windows installer exe

1. Install uv.

2. Install Inno Setup.

3. Build the Windows executables with cx_freeze:

   uv run --python 3.12 --group freeze cx_freeze_setup.py build_exe
   

4. Build the Windows installer with Inno Setup:

   "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\windows.iss
   

The installer will be built as dist\ProCustodibusAgentInstaller.exe.

Contributing

• Code of Conduct
• File a Bug
• Report a Vulnerability
• Submit a Patch

Resources

• Home page: https://www.procustodibus.com/
• Documentation: https://docs.procustodibus.com/guide/agents/run/
• Changelog: https://docs.procustodibus.com/guide/agents/download/#changelog
• Issue tracker: https://todo.sr.ht/~arx10/procustodibus
• Mailing list: https://lists.sr.ht/~arx10/procustodibus
• Source code: https://git.sr.ht/~arx10/procustodibus-agent

License

The MIT License