wyrmctl

Owner-scoped GitOps for Nginx Proxy Manager

Validate desired-state YAML, plan safe owner-scoped changes, apply clean reconciles, and adopt existing NPM resources only when you ask for it.

wyrmctl is the Python package and console script for declarative, owner-scoped Nginx Proxy Manager automation. It manages proxy hosts, certificates, access lists, redirection hosts, dead hosts, streams, users, settings, and provider-backed DNS records without silently mutating foreign-owned resources.

Supported Python Versions

wyrmctl supports Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Why wyrmctl

• Owner-scoped reconciliation instead of global mutable state
• Explicit plan, apply, and adopt flows instead of ad hoc API scripting
• Safe reference handling for certificates and access lists
• Fail-closed behavior when the target NPM schema does not support a required operation
• CLI-first workflows that fit GitOps, CI, and controlled repair operations
• Independently versioned contracts, reproducibility lockfiles, and immutable reviewed plan artifacts
• Transactional adjacent migrations with backups, chained ledgers, leases, and explicit recovery classification

FAQ

What is wyrmctl?

Answer: wyrmctl is a GitOps-style controller for Nginx Proxy Manager that reads desired-state YAML, compares it to the live NPM API, and produces safe owner-scoped plans before any mutation happens.

What problem does wyrmctl solve?

Answer: wyrmctl replaces manual NPM clicking and one-off API scripts with repeatable desired state, explicit adoption, conflict detection, and controlled reconciliation for reverse-proxy resources.

Does wyrmctl modify resources it does not own?

Answer: No. wyrmctl treats NPM resources as owner-scoped, refuses to mutate foreign-owned resources, and only attaches metadata to unmanaged resources when you run wyrmctl adopt.

How does wyrmctl handle certificate issuance and rotation?

Answer: wyrmctl treats certificates as declarative resources in the same desired state as proxy hosts. Issuance happens when a desired certificate must be created, and rotation happens through explicit reconcile policy rather than hidden mutation of unrelated resources.

Can wyrmctl adopt existing manually created NPM resources?

Answer: Yes. wyrmctl adopt can attach wyrmctl ownership metadata to compatible unmanaged resources so future plans and applies can manage them under explicit owner scope.

Install

Use pipx for an isolated CLI install:

pipx install wyrmctl
wyrmctl --version

Use uv if you manage tools with uv:

uv tool install wyrmctl
wyrmctl --help

Use pip inside an existing virtual environment:

python -m venv .venv
. .venv/bin/activate
python -m pip install wyrmctl
wyrmctl --help

PowerShell activation:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install wyrmctl
wyrmctl --help

Configure NPM

Set Nginx Proxy Manager API credentials as environment variables:

export NPM_BASE_URL=http://127.0.0.1:81/api
export NPM_IDENTITY=admin@example.com
export NPM_SECRET=changeme

Or pass them directly:

wyrmctl --base-url http://127.0.0.1:81/api --identity admin@example.com --secret changeme health

Quick Start

Validate desired state without touching the API:

wyrmctl validate ./desired-state
wyrmctl --output json validate ./desired-state

Plan owner-scoped changes:

wyrmctl plan ./desired-state --owner workload-a

Apply a clean plan:

wyrmctl apply ./desired-state --owner workload-a

Adopt unmanaged matching resources:

wyrmctl adopt ./desired-state --owner workload-a
wyrmctl adopt ./desired-state --owner workload-a --allow-field-drift

Desired State

Every managed resource needs wyrmctl ownership metadata:

apiVersion: wyrmctl.com/v1
schemaVersion: 2
proxy_hosts:
  - domain_names: [app.example.com]
    forward_scheme: http
    forward_host: app
    forward_port: 3000
    meta:
      managed_by: wyrmctl
      owner: workload-a
      resource_id: proxy.app

References use resource_id values:

apiVersion: wyrmctl.com/v1
schemaVersion: 2
certificates:
  - name: wildcard-example
    domain_names: ["*.example.com", example.com]
    certificate_type: letsencrypt
    api_payload:
      provider: letsencrypt
    meta:
      managed_by: wyrmctl
      owner: workload-a
      resource_id: cert.wildcard-example
access_lists:
  - name: private-admins
    api_payload:
      satisfy_any: 0
      items: []
      clients: []
    meta:
      managed_by: wyrmctl
      owner: workload-a
      resource_id: acl.private-admins
proxy_hosts:
  - domain_names: [app.example.com]
    forward_host: app
    forward_port: 3000
    certificate_ref: cert.wildcard-example
    access_list_ref: acl.private-admins
    ssl_forced: 1
    allow_websocket_upgrade: 1
    caching_enabled: 1
    block_exploits: 1
    meta:
      managed_by: wyrmctl
      owner: workload-a
      resource_id: proxy.app

More Documentation

• Related PyPI package: https://pypi.org/project/wyrmctl-namecheap/
• Repository: https://github.com/groupsum/wyrmctl
• Examples: https://github.com/groupsum/wyrmctl/tree/master/examples/desired-state
• Docs: https://github.com/groupsum/wyrmctl/tree/master/docs