pr0xteus

pr0xteus

pr0xteus is the not-an-open-proxy bit between a trusted service and a WireGuard-backed SOCKS5 exit. The operator owns the local pool policy. Callers can ask for an approved country or pool; they cannot smuggle Docker flags, host paths, images, or arbitrary provider configs into the daemon.

For the actual setup — local config, a complete pool example, and proof that a controller-fronted SOCKS5 exit works — read references/setup.md before touching the stack.

Security and safety

• This skill is for an instance the user already runs and trusts. Do not hunt through the workspace for tokens, provider bundles, or Docker config. Take PR0XTEUS_URL and PR0XTEUS_API_TOKEN from the environment or ask.
• Allocating a proxy starts or reuses a configured WireGuard cell. It can spend provider capacity and sends later traffic through the operator's exit, so only request the country, pool, and task the user actually named.
• A returned socks5:// URL is a short-lived bearer capability for the controller's SOCKS gateway. Keep it out of logs, issue trackers, and public services. Trusted host and container clients can use it directly; only the controller talks to the selected cell's private address.
• pr0xteus has no MCP endpoint. This is a documentation skill, not a fake bridge plugin with invented tools.

Use it for

• Giving a trusted workload a configured country-specific SOCKS5 exit.
• Checking whether the controller is alive or inspecting configured pools and their hot-tunnel state.
• Replacing a broken SOCKS5 assignment while avoiding the same old cell.
• Inspecting live cells and their traffic (/v1/cells), or destroying one on demand — see references/setup.md.
• Wiring a Go service through pkg/client, with VPN-only traffic by default or explicit public-first fallback where that makes sense.

Do not use it for

• A public or anonymous proxy service.
• Provider-account provisioning, config scraping, or random WireGuard surgery outside the operator-owned pool policy.
• An untrusted caller, public proxy use case, or a destination the operator has not approved.

Talk to a running controller

Set the private control URL and bearer token supplied by the operator:

export PR0XTEUS_URL=http://127.0.0.1:8000
export PR0XTEUS_API_TOKEN=replace-with-the-token-from-your-secret-store

auth_header=(--header @<(printf 'Authorization: Bearer %s' "$PR0XTEUS_API_TOKEN"))

Health lives on the separate metrics listener and deliberately has no token:

curl --fail --silent http://127.0.0.1:9091/healthz

Ask for the configured US route:

curl --fail-with-body --request POST \
  "${auth_header[@]}" \
  --header 'Content-Type: application/json' \
  --data '{"country":"US"}' \
  "$PR0XTEUS_URL/v1/proxies"

The response contains url, pool, exitCountry, and expiresAt. The URL works from the host or another reachable trusted client: it authenticates to the controller, which forwards to the chosen cell without resolving the destination itself. The setup reference shows a direct curl --proxy proof.

Inspect active exits without creating another lease:

curl --fail-with-body "${auth_header[@]}" \
  "$PR0XTEUS_URL/v1/proxies?limit=100" | jq .

Every collection route (/v1/proxies, /v1/pools, and /v1/cells) accepts limit and offset and returns its items plus limit, offset, and total.

Inspect the operator view:

curl --fail-with-body "${auth_header[@]}" "$PR0XTEUS_URL/v1/pools" | jq .

Replace a bad assignment

There is no lease-release endpoint. pr0xteus records the assignment, finishes the API request, then keeps a healthy cell warm until its idle policy reaps it. If the workload cannot use an allocated proxy, request another one and exclude the old URL:

curl --fail-with-body --request POST \
  "${auth_header[@]}" \
  --header 'Content-Type: application/json' \
  --data '{"country":"US","excludeProxy":"socks5://previous-lease-id:previous-secret@127.0.0.1:1080"}' \
  "$PR0XTEUS_URL/v1/proxies"

Go client

The public pkg/client package requests a proxy, builds an HTTP client around it, and can preflight that the exit IP changes. Keep the control token in the service's secret store and pass it with client.WithBearerToken; the package doc comment contains the full shape.

Read references/setup.md before changing local pool policy or operating the persistent stack.