pr0xteus

Private, on-demand WireGuard exits for applications and containers. Give pr0xteus authorized WireGuard configurations, then request short-lived, credentialed SOCKS5 and HTTP proxy URLs from approved pools. Your host does not become a VPN client, and callers never receive provider configuration.
How it works
A controller selects an approved configuration and starts an isolated Docker cell through a restricted socket proxy. The cell waits for a WireGuard handshake, then serves its private proxy. Clients use the controller's lease-authenticated SOCKS5 or HTTP gateway. The controller reports traffic and destinations and removes idle or unhealthy cells.
The supplied stack binds API, metrics and proxy ports to host loopback. An optional Tailscale sidecar provides private remote access without publishing host ports. See controller internals and security boundaries.
Quick start
You need Linux, Docker with Compose and an authorized WireGuard .conf file. No source checkout or host Go installation is needed.
Review and run the installer:
curl -fsSL https://raw.githubusercontent.com/psyb0t/pr0xteus/main/install.sh | bash
It installs ~/.local/bin/pr0xteus, creates owner-only configuration under ~/.config/pr0xteus/ and generates the API token. The installer selects the latest tagged release and its matching cell image.
Copy your WireGuard file:
cp /path/to/your-vpn.conf ~/.config/pr0xteus/secrets/wireguard/us.conf
Configure the pool and routing:
# ~/.config/pr0xteus/secrets/pools.yaml
pools:
us:
region: north-america
purpose: private-service-egress
configs: [us]
exit_countries:
us: US
# ~/.config/pr0xteus/config/egress-routing.yaml
country_to_pool:
US: us
default_pool: us
Start the stack:
pr0xteus start
pr0xteus status
The default API is http://127.0.0.1:8000. Health and metrics use http://127.0.0.1:9091. Edit the generated .env for ports and operator settings. See installation and upgrades for system-wide installs, rolling images, permissions and preserved configuration.
Allocate an exit and use it
This Bash example needs curl and jq. It reads the token from the installed configuration rather than putting it in shell history:
token="$(sed -n 's/^PR0XTEUS_API_TOKEN=//p' ~/.config/pr0xteus/.env)"
auth=(--header @<(printf 'Authorization: Bearer %s' "$token"))
allocation="$(
curl --fail-with-body --request POST "${auth[@]}" \
--header 'Content-Type: application/json' \
--data '{"country":"US"}' \
http://127.0.0.1:8000/v1/proxies
)"
socks5_proxy="$(jq -er '.proxies.socks5' <<<"$allocation")"
http_proxy="$(jq -er '.proxies.http' <<<"$allocation")"
curl --fail --silent --show-error --proxy "$socks5_proxy" https://api.ipify.org
curl --fail --silent --show-error --proxy "$http_proxy" https://api.ipify.org
unset token allocation socks5_proxy http_proxy
unset -a auth
Both URLs share the selected cell, lease credentials and expiry. They target the controller, not an unpublished cell address. DNS and outbound traffic happen through the cell's WireGuard tunnel. Returned URLs are credentials too: do not log or share them. The complete walkthrough covers egress proof, bad allocations and readiness checks.
Private remote access
The optional Tailscale or Headscale sidecar has its own persistent tailnet identity. API bearer authentication and proxy lease credentials still apply. The metrics listener has no application authentication, so restrict its access with tailnet ACLs. See Tailscale setup.
API and agent integrations
The JSON API allocates leases, lists approved pools, inventories live cells and their traffic, and destroys selected cells. Collection endpoints use limit and offset. Read the API reference for request, response and error contracts.
A public Go client handles allocation and retries. Documentation skills are available for Claude Code, Codex and OpenClaw; see agent integrations. pr0xteus is an HTTP service, not an MCP server.
Development
Source development uses Docker-backed Make targets:
make help
make lint
make test-coverage
make sec
make generate
Tests use the race detector and self-contained Testcontainers infrastructure. Real-provider tests are opt-in. See development and testing for image builds, coverage, production-image API tests and local stack commands.
Documentation
The full documentation is at psyb0t.github.io/pr0xteus.
| Section |
What it covers |
| Complete setup walkthrough |
Install, configure, allocate and prove egress |
| Installation and upgrades |
Installer modes, the pr0xteus command, upgrades, Tailscale |
| Configuration |
Pool and routing files, every setting, cell image pairing |
| Direct Docker deployment |
Running the stack without the wrapper |
| Control API |
Requests, responses and errors |
| Go client |
pkg/client retries, modes and preflight |
| Agent integrations |
Claude Code, Codex and OpenClaw |
| Monitoring |
Health, metrics and logs |
| Troubleshooting |
Startup refusals and failed allocations |
| Security boundaries |
What is isolated and what you protect |
| Controller internals |
Controller and cell design |
| Development |
Building, testing and CI |
The changelog lists every release.

License and notices
The project source is MIT licensed. Third-party notices and vendor/ contain dependency licenses and attribution.