# trailofbits/algo architecture

> Architecture diagram of the GitHub repository trailofbits/algo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trailofbits/algo
- Repository: https://github.com/trailofbits/algo

## Overview

Algo VPN is an Ansible-based deployment tool for creating a personal WireGuard and IPsec VPN server. The principal workflow is to configure users and options, launch deployment, provision a supported cloud or Ubuntu host, configure VPN and optional server services, and generate client credentials and profiles. The graph preserves the documented provider, DNS, SSH-tunneling, privacy, and user-management capabilities. Most playbooks and roles were not sampled, so deployment links beyond README statements are marked unverified rather than asserted as inspected calls.

Main entry points: [`playbooks`](https://github.com/trailofbits/algo/tree/main/playbooks) (Cloud setup playbooks), [`server.yml`](https://github.com/trailofbits/algo/blob/main/server.yml) (VPN server configuration), [`main.yml`](https://github.com/trailofbits/algo/blob/main/main.yml) (Ansible deployment), [`roles/wireguard/tasks/main.yml`](https://github.com/trailofbits/algo/blob/main/roles/wireguard/tasks/main.yml) (WireGuard setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_launcher["Deployment launcher"]
  node_configuration["Deployment configuration<br/>[config.cfg]"]
  node_orchestrator["Ansible deployment<br/>[main.yml]"]
  node_cloud_playbooks["Cloud setup playbooks"]
end

subgraph group_providers["Cloud providers"]
  node_digitalocean["DigitalOcean provisioning<br/>[main.yml]"]
  node_ec2["EC2 provisioning<br/>[main.yml]"]
  node_lightsail["Lightsail provisioning<br/>[main.yml]"]
  node_azure["Azure provisioning<br/>[main.yml]"]
  node_gce["GCE provisioning<br/>[main.yml]"]
  node_other_providers["Other cloud provisioning"]
end

subgraph group_vpn["VPN and clients"]
  node_server["VPN server configuration<br/>[server.yml]"]
  node_wireguard["WireGuard setup<br/>[main.yml]"]
  node_ipsec["IPsec setup<br/>[main.yml]"]
  node_key_derivation["WireGuard key derivation<br/>[x25519_pubkey.py]"]
  node_client_profiles["Client profile generation<br/>[mobileconfig.yml]"]
  node_user_management["User management<br/>[users.yml]"]
  node_client_configs["Generated client configurations<br/>[client_configs.yml]"]
end

subgraph group_server_features["Server features"]
  node_dns["Local DNS and ad blocking<br/>[main.yml]"]
  node_ssh_tunneling["SSH tunneling<br/>[main.yml]"]
  node_privacy["Privacy enhancements<br/>[main.yml]"]
end

node_operator(("VPN operator"))
node_cloud_provider["Cloud provider"]
node_client(("VPN client device"))

node_operator -->|"runs deployment"| node_launcher
node_operator -->|"sets options"| node_configuration
node_launcher -.->|"starts deployment"| node_orchestrator
node_orchestrator -.->|"provisions host"| node_cloud_playbooks
node_cloud_playbooks -.->|"selects provider"| node_digitalocean
node_cloud_playbooks -.->|"selects provider"| node_ec2
node_cloud_playbooks -.->|"selects provider"| node_lightsail
node_cloud_playbooks -.->|"selects provider"| node_azure
node_cloud_playbooks -.->|"selects provider"| node_gce
node_cloud_playbooks -.->|"selects provider"| node_other_providers
node_cloud_provider -->|"hosts deployment"| node_cloud_playbooks
node_orchestrator -.->|"configures server"| node_server
node_server -.->|"configures VPN"| node_wireguard
node_server -.->|"configures VPN"| node_ipsec
node_wireguard -.->|"derives keys"| node_key_derivation
node_wireguard -.->|"generates profiles"| node_client_profiles
node_ipsec -.->|"generates profiles"| node_client_configs
node_server -.->|"manages users"| node_user_management
node_server -->|"optionally configures"| node_dns
node_server -->|"optionally configures"| node_ssh_tunneling
node_server -->|"configures privacy"| node_privacy
node_client_configs -->|"configures device"| node_client
node_client_profiles -->|"configures device"| node_client

click node_launcher "https://github.com/trailofbits/algo/blob/main/algo"
click node_configuration "https://github.com/trailofbits/algo/blob/main/config.cfg"
click node_orchestrator "https://github.com/trailofbits/algo/blob/main/main.yml"
click node_cloud_playbooks "https://github.com/trailofbits/algo/tree/main/playbooks"
click node_digitalocean "https://github.com/trailofbits/algo/blob/main/roles/cloud-digitalocean/tasks/main.yml"
click node_ec2 "https://github.com/trailofbits/algo/blob/main/roles/cloud-ec2/tasks/main.yml"
click node_lightsail "https://github.com/trailofbits/algo/blob/main/roles/cloud-lightsail/tasks/main.yml"
click node_azure "https://github.com/trailofbits/algo/blob/main/roles/cloud-azure/tasks/main.yml"
click node_gce "https://github.com/trailofbits/algo/blob/main/roles/cloud-gce/tasks/main.yml"
click node_other_providers "https://github.com/trailofbits/algo/tree/main/roles"
click node_server "https://github.com/trailofbits/algo/blob/main/server.yml"
click node_wireguard "https://github.com/trailofbits/algo/blob/main/roles/wireguard/tasks/main.yml"
click node_ipsec "https://github.com/trailofbits/algo/blob/main/roles/strongswan/tasks/main.yml"
click node_key_derivation "https://github.com/trailofbits/algo/blob/main/library/x25519_pubkey.py"
click node_client_profiles "https://github.com/trailofbits/algo/blob/main/roles/wireguard/tasks/mobileconfig.yml"
click node_user_management "https://github.com/trailofbits/algo/blob/main/users.yml"
click node_dns "https://github.com/trailofbits/algo/blob/main/roles/dns/tasks/main.yml"
click node_ssh_tunneling "https://github.com/trailofbits/algo/blob/main/roles/ssh_tunneling/tasks/main.yml"
click node_privacy "https://github.com/trailofbits/algo/blob/main/roles/privacy/tasks/main.yml"
click node_client_configs "https://github.com/trailofbits/algo/blob/main/roles/strongswan/tasks/client_configs.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_configuration,node_orchestrator,node_cloud_playbooks,node_client toneBlue
class node_digitalocean,node_ec2,node_lightsail,node_azure,node_gce,node_other_providers toneAmber
class node_server,node_wireguard,node_ipsec,node_key_derivation,node_client_profiles,node_user_management,node_client_configs toneMint
class node_dns,node_ssh_tunneling,node_privacy toneRose
class node_operator,node_cloud_provider toneIndigo
```

## Components

### Deployment

- [Deployment launcher](https://github.com/trailofbits/algo/blob/main/algo): `algo`
- [Deployment configuration](https://github.com/trailofbits/algo/blob/main/config.cfg): `config.cfg`
- [Ansible deployment](https://github.com/trailofbits/algo/blob/main/main.yml): `main.yml`
- [Cloud setup playbooks](https://github.com/trailofbits/algo/tree/main/playbooks): `playbooks`

### Cloud providers

- [DigitalOcean provisioning](https://github.com/trailofbits/algo/blob/main/roles/cloud-digitalocean/tasks/main.yml): `roles/cloud-digitalocean/tasks/main.yml`
- [EC2 provisioning](https://github.com/trailofbits/algo/blob/main/roles/cloud-ec2/tasks/main.yml): `roles/cloud-ec2/tasks/main.yml`
- [Lightsail provisioning](https://github.com/trailofbits/algo/blob/main/roles/cloud-lightsail/tasks/main.yml): `roles/cloud-lightsail/tasks/main.yml`
- [Azure provisioning](https://github.com/trailofbits/algo/blob/main/roles/cloud-azure/tasks/main.yml): `roles/cloud-azure/tasks/main.yml`
- [GCE provisioning](https://github.com/trailofbits/algo/blob/main/roles/cloud-gce/tasks/main.yml): `roles/cloud-gce/tasks/main.yml`
- [Other cloud provisioning](https://github.com/trailofbits/algo/tree/main/roles): `roles`

### VPN and clients

- [VPN server configuration](https://github.com/trailofbits/algo/blob/main/server.yml): `server.yml`
- [WireGuard setup](https://github.com/trailofbits/algo/blob/main/roles/wireguard/tasks/main.yml): `roles/wireguard/tasks/main.yml`
- [IPsec setup](https://github.com/trailofbits/algo/blob/main/roles/strongswan/tasks/main.yml): `roles/strongswan/tasks/main.yml`
- [WireGuard key derivation](https://github.com/trailofbits/algo/blob/main/library/x25519_pubkey.py): `library/x25519_pubkey.py`
- [Client profile generation](https://github.com/trailofbits/algo/blob/main/roles/wireguard/tasks/mobileconfig.yml): `roles/wireguard/tasks/mobileconfig.yml`
- [User management](https://github.com/trailofbits/algo/blob/main/users.yml): `users.yml`
- [Generated client configurations](https://github.com/trailofbits/algo/blob/main/roles/strongswan/tasks/client_configs.yml): `roles/strongswan/tasks/client_configs.yml`

### Server features

- [Local DNS and ad blocking](https://github.com/trailofbits/algo/blob/main/roles/dns/tasks/main.yml): `roles/dns/tasks/main.yml`
- [SSH tunneling](https://github.com/trailofbits/algo/blob/main/roles/ssh_tunneling/tasks/main.yml): `roles/ssh_tunneling/tasks/main.yml`
- [Privacy enhancements](https://github.com/trailofbits/algo/blob/main/roles/privacy/tasks/main.yml): `roles/privacy/tasks/main.yml`

### Other components

- **VPN operator**
- **Cloud provider**
- **VPN client device**

## Connections

- VPN operator → Deployment launcher: runs deployment (evidence: `README.md`)
- VPN operator → Deployment configuration: sets options (evidence: `README.md`)
- Deployment launcher → Ansible deployment: starts deployment
- Ansible deployment → Cloud setup playbooks: provisions host
- Cloud setup playbooks → DigitalOcean provisioning: selects provider
- Cloud setup playbooks → EC2 provisioning: selects provider
- Cloud setup playbooks → Lightsail provisioning: selects provider
- Cloud setup playbooks → Azure provisioning: selects provider
- Cloud setup playbooks → GCE provisioning: selects provider
- Cloud setup playbooks → Other cloud provisioning: selects provider
- Cloud provider → Cloud setup playbooks: hosts deployment (evidence: `README.md`)
- Ansible deployment → VPN server configuration: configures server
- VPN server configuration → WireGuard setup: configures VPN
- VPN server configuration → IPsec setup: configures VPN
- WireGuard setup → WireGuard key derivation: derives keys
- WireGuard setup → Client profile generation: generates profiles
- IPsec setup → Generated client configurations: generates profiles
- VPN server configuration → User management: manages users
- VPN server configuration → Local DNS and ad blocking: optionally configures (evidence: `README.md`)
- VPN server configuration → SSH tunneling: optionally configures (evidence: `README.md`)
- VPN server configuration → Privacy enhancements: configures privacy (evidence: `README.md`)
- Generated client configurations → VPN client device: configures device (evidence: `README.md`)
- Client profile generation → VPN client device: configures device (evidence: `README.md`)
