pr0xteus

module
v0.11.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT

README

pr0xteus

CI version license coverage Docker Pulls

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.

Sponsor

Buy Me a Coffee

License and notices

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

Directories

Path Synopsis
cmd
cellproxy command
Command cellproxy is the metrics-emitting SOCKS5 proxy that runs inside a pr0xteus cell in place of microsocks.
Command cellproxy is the metrics-emitting SOCKS5 proxy that runs inside a pr0xteus cell in place of microsocks.
internal
app
pkg/cellproxy
Package cellproxy is the metrics-emitting SOCKS5 proxy that runs inside a pr0xteus cell in place of microsocks.
Package cellproxy is the metrics-emitting SOCKS5 proxy that runs inside a pr0xteus cell in place of microsocks.
pkg/services/pr0xteus
Package pr0xteus implements logical pools of cell-backed WireGuard tunnels with on-demand spawn, idle reap, and an authenticated HTTP control API.
Package pr0xteus implements logical pools of cell-backed WireGuard tunnels with on-demand spawn, idle reap, and an authenticated HTTP control API.
pkg
client
Package client is the HTTP client library consumers use to send outbound requests through pr0xteus.
Package client is the HTTP client library consumers use to send outbound requests through pr0xteus.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL