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

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

Contributing

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

Metadata

Release files for procustodibus_agent 1.10.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for procustodibus_agent 1.10.3
File	Size	Uploaded
procustodibus_agent-1.10.3.tar.gz	269.2 kB	Jul 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for procustodibus_agent 1.10.3
File	Interpreter	ABI	Platform	Reset
procustodibus_agent-1.10.3-py3-none-any.whl 61.5 kB Jul 26, 2026	Python 3	none	any	Details

Total release size: 330.8 kB

Release files / procustodibus_agent-1.10.3.tar.gz

Download URL	procustodibus_agent-1.10.3.tar.gz
Size	269.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`1a5009fee4e41c4f7ff2cb5e03d1ba439408b2350e26995d45c760e6b5524261`
BLAKE2b-256 checksum How to use checksums	`bf318501cc2baf724f686fb1527fe4c39072af4cb6807e25d25b0e41b65d1287`
Upload date	Jul 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.9 {"installer":{"name":"uv","version":"0.10.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / procustodibus_agent-1.10.3-py3-none-any.whl

Download URL	procustodibus_agent-1.10.3-py3-none-any.whl
Size	61.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2a645f7e2134b0c4a2e816b8bccaf1af90f89771045f191b096c2a4bef813430`
BLAKE2b-256 checksum How to use checksums	`f65c28be6e47cb3aa88ebe83622c6398688b8a9f4b350b4716093a0f2c180a1e`
Upload date	Jul 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.9 {"installer":{"name":"uv","version":"0.10.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`