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.

Read-only mode

By default, the admin server can both query and mutate runtime state — targets, pools, and providers created or edited through the GraphQL API are held in the config store (or, with no config store configured, an in-process store that doesn’t survive a restart). Set server.adminReadOnly to run it as monitoring-only instead: every GraphQL mutation is rejected, and all config comes from the YAML file alone.

server:
  admin: true
  adminReadOnly: true

PROXY_HOPPER_ADMIN_READ_ONLY=true
# or: proxy-hopper admin --config config.yaml --admin-read-only

Rejected mutations fail with a PermissionError in the GraphQL errors array — the same shape as a role-based permission failure, so existing error handling in a client or the admin UI needs no special case for it. Queries are completely unaffected: status, targets, pools, providers, and targetMetrics all keep working, which is the point — you still get a fully usable monitoring surface, just not a mutable one.

adminReadOnly is checked before role-based auth, so it applies even when auth.enabled is false. It’s also independent of configStoreUrl/configStore.dialect — the two combine into four real deployment shapes:

`adminReadOnly`	Config store	Result
`false`	unset	Default. Mutations work but don’t survive a restart.
`false`	set	Mutations work and are durable.
`true`	unset	No database anywhere. All config from YAML; admin server is monitoring-only.
`true`	set	Durable config, but changes only ever happen by redeploying YAML — never via the API. Useful for GitOps-managed config where you still want the store’s cross-replica sharing.

The status query (and GET /api/v1/status) reports the current mode via readOnly, so a client or dashboard can detect it without attempting a mutation first:

{
  status {
    readOnly
  }
}

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

Read-only mode

Authentication

Obtaining a JWT

GraphQL playground

Ports summary

​Overview

​Embedded vs separate process

​Enabling the admin server

​Read-only mode

​Authentication

​Obtaining a JWT

​GraphQL playground

​Ports summary

Overview

Embedded vs separate process

Enabling the admin server

Read-only mode

Authentication

Obtaining a JWT

GraphQL playground

Ports summary