Admin Server

Overview

Installing proxy-hopper-webserver (pip install proxy-hopper-webserver) adds a second HTTP server, on its own port (default 8081), exposing:

Endpoint	Auth required	Description
`GET /health`	No	Liveness check — always returns `{"status": "ok"}`
`POST /auth/login`	No	Exchange admin credentials for a JWT
`GET /api/v1/status`	Read	Current target list and server state
`GET /graphql`	Read	GraphQL playground (browser UI)
`POST /graphql`	Read / Write	GraphQL API

The GraphQL API lets you query and mutate targets, IP pools, and providers at runtime — without restarting the server and without editing the config file.

Embedded vs separate process

There are two ways to run the admin server, and which one is correct depends entirely on which backend you’re using:

Backend	How to run admin	Why
`redis`	`proxy-hopper admin --config config.yaml` (separate process/pod)	Both processes connect to the same Redis instance, so the admin API sees real, live pool/quarantine/target state. This is the recommended production shape — scale the proxy independently, run a single admin replica.
`memory`	`proxy-hopper run --config config.yaml --admin` (embedded, same process)	The memory backend is plain in-process asyncio queues and dicts — it cannot be shared across OS processes. A separately-run `proxy-hopper admin` process with `backend: memory` gets its own private, disconnected backend: it shows only what was seeded from YAML at its own startup, never any live runtime state (pool rotation, quarantine, admin-made edits). `--admin` avoids this entirely by running both the proxy listener and the admin server in one process, sharing one backend object directly — no cross-process boundary to fail to cross.

Since backend: memory only ever supports a single proxy instance anyway (there’s no way to share its state across replicas without Redis), embedding admin doesn’t cost you anything you didn’t already have — there was never going to be more than one node.

# Single-container / homelab / Docker Compose: proxy + admin together
proxy-hopper run --config config.yaml --admin

# Redis-backed HA: proxy replicas scale independently, one admin replica
proxy-hopper run --config config.yaml --backend redis --redis-url redis://redis:6379/0
proxy-hopper admin --config config.yaml --backend redis --redis-url redis://redis:6379/0

If proxy-hopper-webserver isn’t installed, --admin fails startup immediately with a clear error rather than silently running without it — the same fail-fast behavior as requesting --backend redis without proxy-hopper-redis installed.

Enabling the admin server

Both the embedded (run --admin) and separate-process (admin subcommand) topologies share the same server.admin/adminPort/adminHost config fields:

server:
  admin: true
  adminPort: 8081        # default — omit to accept the default

Or via environment variable:

PROXY_HOPPER_ADMIN=true
PROXY_HOPPER_ADMIN_PORT=8081

The admin server runs on 0.0.0.0 by default. In production, restrict access at the network level — bind it to an internal interface or place it behind a firewall/ingress that only your operations tooling can reach.

Authentication

If auth.enabled: true is set, every request to protected endpoints must include an Authorization: Bearer <token> header. The token can be:

A JWT obtained from POST /auth/login (requires auth.admin to be configured)
An API key declared in auth.apiKeys
An OIDC token (when auth.oidc is configured)

The /health endpoint is always public. When auth is disabled, all endpoints are accessible without credentials. This is acceptable for internal-only deployments where the admin port is not exposed outside your network.

Obtaining a JWT

curl -X POST http://localhost:8081/auth/login \
  -d "username=admin&password=mypassword"

Returns:

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Pass the token in subsequent requests:

curl -H "Authorization: Bearer eyJ..." \
     http://localhost:8081/api/v1/status

GraphQL playground

With the admin server running, open http://localhost:8081/graphql in a browser to access the interactive GraphQL playground. You can explore the schema, run queries, and test mutations directly from the browser. If auth is enabled, add your token via the playground’s “Headers” panel:

{
  "Authorization": "Bearer eyJ..."
}

See GraphQL API for the full query and mutation reference.

Ports summary

Port	Purpose	Config key	Env var
`8080`	Proxy (client traffic)	`server.port`	`PROXY_HOPPER_PORT`
`8081`	Admin server	`server.adminPort`	`PROXY_HOPPER_ADMIN_PORT`
`9090`	Prometheus metrics	`server.metricsPort`	`PROXY_HOPPER_METRICS_PORT`

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Overview

Embedded vs separate process

Enabling the admin server

Authentication

Obtaining a JWT

GraphQL playground

Ports summary

​Overview

​Embedded vs separate process

​Enabling the admin server

​Authentication

​Obtaining a JWT

​GraphQL playground

​Ports summary

Overview

Embedded vs separate process

Enabling the admin server

Authentication

Obtaining a JWT

GraphQL playground

Ports summary