trailofbits/algo: a personal WireGuard and IPsec VPN built from Ansible playbooks

What Algo actually provisions, and who it is written for

Algo is not a VPN service. It is a set of Ansible scripts that builds a VPN server on a cloud virtual machine that you pay for and that belongs to you. The README describes it as scripts that "simplify the setup of a personal WireGuard and IPsec VPN", using "the most secure defaults available". The target reader is someone who is willing to run a deployment from a terminal, hold cloud provider credentials locally, and manage per-device configuration files afterwards.

The protocol support is deliberately narrow. IPsec means IKEv2 with AES-GCM, SHA2 and P-256, aimed at iOS, macOS and Linux. WireGuard covers those three plus Android and Windows 11. There is no OpenVPN, no L2TP, no IKEv1 and no RSA. The README calls these anti-features rather than gaps, which tells you the maintainers treat protocol breadth as a liability rather than a feature to be added later.

That framing matters when you evaluate it. A team that needs to support an old Android tablet, a router with only OpenVPN support, or a corporate client that speaks IKEv1 is not the audience. Algo is for individuals and small groups who can dictate the client software on every device that connects.

How the Ansible deployment works, from config.cfg to configs/

The data flow is linear and readable from the repository layout. You keep a local copy of the scripts, edit config.cfg, and run the platform launcher. Ansible then provisions a new VM at the provider you selected, installs and configures the VPN services, and writes client material back into a local configs/ directory. The repository separates this into playbooks: main.yml, server.yml and cloud.yml for the server side, deploy_client.yml for client generation, and destroy.yml for teardown.

On success the launcher prints a boxed message stating that your Algo server is running, that config files and certificates are in ./configs/, and that the local DNS resolver is at 172.16.0.1. The same block prints the p12 and SSH key password for new users, the CA key password, and the shell command to reach the server, which the README shows as ssh -F configs/<server_ip>/ssh_config <hostname>. Everything under configs/ is grouped by the server IP address.

Two design choices stand out. First, users are declared in config.cfg before deployment, one user per device, which means the client inventory is fixed at build time unless you keep the certificate authority. Second, the server runs Ubuntu 22.04 LTS with automatic security updates, so patching the operating system is delegated to the distribution rather than to Ansible reruns. The README's own FAQ link warns that changing configuration options after deployment may require deploying a brand new server, which is the honest way to describe a system that treats the server as disposable.

Installing Algo and adding your first user

You need a cloud provider account before anything else. The README lists DigitalOcean, Amazon Lightsail, Amazon EC2, Vultr, Microsoft Azure, Google Compute Engine, Scaleway, DreamCompute, Linode, OpenStack and CloudStack based hosts, and Hetzner Cloud. There is also a documented path for your own Ubuntu server, which the README marks as being for advanced users.

Get the scripts onto your local machine. Either download the ZIP archive, which unzips into a directory named algo-master, or clone the repository:

git clone https://github.com/trailofbits/algo.git

Open config.cfg and set the users list. The README advises creating a unique user for each device you plan to connect, and to review the other options before deployment rather than after. Then run the launcher for your platform. On macOS and Linux:

./algo

On Windows the repository ships a PowerShell launcher, which the README says uses WSL automatically because Ansible needs a Unix-like environment:

.\algo.ps1

The first run installs the required Python environment, which the README states is Python 3.11 or newer; later runs start immediately. When the deployment finishes you should see the congratulations block with the configs/ path, the DNS resolver address, and the generated passwords. After that, client setup depends on the platform. For iOS and macOS, Algo writes wireguard/<username>.conf and a matching QR code image; you install the WireGuard app and either scan the QR code or import the configuration file. For IPsec, Algo generates Apple profiles that configure the device without extra client software, but the README warns that adding or deleting IPsec users later requires answering yes to the "Do you want to retain the keys (PKI)?" prompt during deployment.

The PKI prompt is the decision that is hard to reverse

The most consequential choice in an Algo deployment is not the cloud provider. It is whether you retain the certificate authority. The README is explicit: if you want to add or delete IPsec users later, you must select yes at the "Do you want to retain the keys (PKI)?" prompt during server deployment, because that preserves the certificate authority needed for user management. Answer no and the CA is gone with the deployment.

This is a real limitation rather than a footnote. WireGuard users are comparatively easy to reason about because each peer has its own key pair and configuration file, and the helper scripts in the repository are described as adding, removing and managing users. IPsec user management after the fact depends entirely on that retained CA. A reader who skims the deployment prompts and accepts the defaults can end up with a server that works fine and cannot be extended without a rebuild.

The same applies to configuration more broadly. The README links to its FAQ with the phrasing that changing your mind about options later "may require you to deploy a brand new server". Treat the deployment as a one-shot artefact: decide the user list, the optional features, and the PKI answer before you run ./algo, not after.

What Algo does not do: anonymity, censorship circumvention, legacy clients

The anti-features section is unusually direct. Algo does not claim to provide anonymity or censorship avoidance, and it does not claim to protect you from the FSB, the MSS, the DGSE, or the FSM. It also does not install Tor or OpenVPN, and it says it does not depend on the security of TLS. If your threat model includes a network that actively blocks VPN protocols, this project does not address it; the README says so in plain language rather than burying it.

Privacy features are narrower than the marketing of most VPN products. The README describes minimal logging, automatic log rotation, and configurable privacy enhancements, plus an optional local DNS resolver that blocks ads. Those are operational hygiene measures, not anonymity. The server still has an IP address registered to your cloud account, and the traffic still terminates there.

The practical failure mode is a client that cannot connect at all. An organisation-standardised on OpenVPN or L2TP will find no configuration path here, and the README frames that as intentional. Algo is the wrong tool when protocol compatibility is a hard requirement, and it is also the wrong tool when the goal is hiding that a VPN is in use.

Algo compared with a hosted VPN subscription

The obvious alternative is a commercial VPN subscription, and the difference is architectural rather than cosmetic. A subscription gives you a client app and a shared pool of provider-operated exit nodes. You do not choose the operating system, you do not hold the keys, and the provider can see the aggregate traffic pattern across its user base. Algo inverts that: you hold cloud credentials, you get an SSH config for the server, and the configs/ directory on your laptop contains the private keys and certificates. The trust anchor moves from the provider to your own machine and your cloud account.

That inversion has costs the subscription does not have. You pay the cloud provider directly, you are responsible for the server existing, and you own the operational surface: the Ubuntu 22.04 LTS base with automatic security updates, the Ansible scripts that provisioned it, and the destroy.yml playbook if you want it gone. A subscription also scales to many devices with no per-device key ceremony, whereas Algo asks you to create a unique user per device in config.cfg.

There is a middle path worth naming: a self-hosted VPN built by hand on a VPS. That gives you the same ownership without Ansible, at the cost of writing the strongSwan and WireGuard configuration yourself. Algo's value is that it encodes those configurations, including the IKEv2 crypto choices and the client profile generation, into playbooks you can read in the repository.

Licence, maintenance and the cost of upgrading

Algo is licensed under AGPL-3.0, and the Dockerfile carries the same identifier in its org.opencontainers.image.licenses label. The AGPL is a strong copyleft licence with a network clause. If you modify Algo and let users interact with it over a network, the licence's terms about offering the corresponding source are the part to read carefully. This is a description of the licence text, not legal advice; if you plan to redistribute a modified Algo or run it as a service for others, have someone qualified review your obligations.

The repository is not archived, and the last push was on 2026-09-09, so the project is being worked on. The release history is uneven in a way worth noting: v1.1 dates to 2019-07-31, v2.0.0 to 2025-08-22, and v2.0.1 to 2025-11-27. The gap between v1.1 and v2.0.0 means anyone running the pre-2.0 line should expect a substantial migration rather than a patch upgrade, and the README's own warning that some configuration changes require a new server applies to version jumps too.

Upgrade cost is therefore dominated by redeployment, not by package management. pyproject.toml pins ansible==12.3.0 and requires Python 3.11 or newer, and the Dockerfile builds on python:3.12-alpine with uv sync --locked. Those pins mean an old local checkout can rot: if you return to an Algo directory a year later, the first run may need to rebuild its Python environment before it can talk to your cloud provider. The Dockerfile also documents a subtle constraint, noting that /algo must remain root-owned for --cap-drop=all compatibility because root without CAP_DAC_OVERRIDE cannot write to files owned by others. That is the kind of detail that matters if you plan to run the containerised path in a hardened environment.

Editorial conclusion

Adopt Algo if you want a personal WireGuard and IKEv2 VPN on a cloud VM you control and you are comfortable running Ansible from your own machine. Do not adopt it if you need OpenVPN, L2TP, IKEv1, or any claim of anonymity; the README lists those as anti-features. Before deploying, decide the users list in config.cfg and whether to retain the PKI, because the FAQ notes that changing your mind later may require deploying a brand new server.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. trailofbits/algo on GitHub