vpnctl

vpnctl is the control plane for a sovereign mesh/VPN fleet: it renders and deploys WireGuard and AmneziaWG hubs, keeps a deterministic 10.13.13.0/24 east-west mesh plus an awg-mesh inter-hub backbone, and fans client egress out through rotating pools (commercial VPNs, Tor, direct VPS IPs) and an explicit-only residential exit. It also manages guest access points, recursive and authoritative DNS, DDNS rendezvous, published Nginx/TLS edges, and the YaCy/SearXNG/Crawl4AI search stack. Everything is declarative: topology.yaml plus secrets.env are the source of truth, vpnctl generate renders host and client bundles, and vpnctl deploy ships them over SSH/rsync. It is Linux-first (x86_64/aarch64) and stateless — any authorized controller can run it and walk away.

Quickstart

Prerequisites: a Rust toolchain (edition 2021), SSH access to the fleet hosts, and ssh/rsync/docker available where the deployer will run.

# 1. Build the single binary
cargo build --release

# 2. Install it on PATH (or invoke ./target/release/vpnctl directly)
install -m 0755 target/release/vpnctl ~/.local/bin/vpnctl

# 3. Create topology.yaml, secrets.env, and the key state
vpnctl init

# 4. Fill in your hosts, exits, and credentials
$EDITOR ~/.config/vpnctl/topology.yaml
$EDITOR ~/.config/vpnctl/secrets.env

# 5. Check config and tooling before touching anything
vpnctl validate
vpnctl doctor

# 6. Render bundles and test connectivity; no remote changes
vpnctl deploy --dry-run

# 7. Deploy to the fleet (start with one canary target)
vpnctl deploy --target proxy1
vpnctl deploy

# 8. Run the MESH / EXIT / CENS / PROX / DNS scenario matrix
vpnctl test

vpnctl init never overwrites existing files unless you pass --force. vpnctl deploy --dry-run is always safe; live deploys run a preflight linter that refuses configurations capable of severing SSH.

Repo map

Path	What lives there
src/config/	Topology schema and defaults, secrets, XDG path resolution, drift checks
src/generator/	Compose, AmneziaWG/WireGuard, DNS, HAProxy fan-out, publish/TLS, client profiles
src/deployer/	SSH/rsync orchestrator, bundle staging, preflight, health checks, teardown
src/cli/	Clap command definitions, handlers, doctor, glossary
src/apps/	YaCy/SearXNG/Crawl4AI lifecycle, upgrades, backups, pool fan-out, watchdog
src/dns/	DDNS publish/receive, rendezvous lookup, and managed public DNS (Namecheap)
src/echoip/	Sovereign echo-IP service (egress verification)
src/proxy/	proxy-ns and proxychains4 integration
src/status/	Fleet status model, WebUI, TUI
src/auth/, src/crypto/	Credential verification, WireGuard keypairs and QR codes
src/test_harness/, src/topology/	Connection-vector model and live test matrix
tests/	Scenario, hardening, simulation, and teardown suites
scripts/	scan-secrets.sh, limit-logs.sh, docker-prune.sh
search/	Upstream configs and overrides for crawl4ai, searxng, yacy
docs/	Proxying and federation guides plus docs/archive/ (historical)
dist/	Generated host/client bundles and cheatsheets (gitignored)

Docs index

Doc	Contents
FAQ.md	Architecture, deployment workflows, disaster-recovery playbooks, apps, DNS, and daily commands
docs/PROXYING.md	Practical recipes for running any program through a fleet exit (proxy-ns, proxychains, Docker, Firefox)
docs/YACY_FEDERATION.md	Pinning YaCy's federation address to the published TLS edge
TODO.md	Fleet inventory, architecture notes, and open work
docs/archive/	Superseded design/handoff docs, kept for historical context only

Security

• Configuration lives in ~/.config/vpnctl/ (topology.yaml, secrets.env, mode 0600); keys and mutable state live in the XDG state dir (~/.local/state/vpnctl/, e.g. state.json at 0600). Generated bundles and live secrets stay out of git; only topology.yaml templates are tracked.

• Run ./scripts/scan-secrets.sh before committing. It scans tracked files by default, --staged for only the index, and --all to also cover untracked non-ignored files. It fails closed (exit 1) on findings.

• Optional pre-commit hook:

  ln -sf ../../scripts/scan-secrets.sh .git/hooks/pre-commit
  

• Never widen proxy ACLs or paste real domains, IPs, or tokens into docs; use example.com/example.net placeholders and the documentation IP ranges.

Getting help

vpnctl --help              # every command, grouped by workflow
vpnctl <command> --help    # per-command flags and examples
vpnctl cheatsheet          # live proxy port map (also --format yaml|json)
vpnctl glossary [term]     # definitions for mesh, backbone, exits, fan-out, ...
vpnctl doctor              # config, credential, and tool diagnostics
vpnctl completions zsh     # static: bash | zsh | fish | powershell | elvish
vpnctl completions --install  # write bash + zsh completions under ~/.local/share
source <(COMPLETE=zsh vpnctl)  # dynamic: also completes host names and exit specs