PQ-Proxy On-Premise

01 Get a license

PQ-Proxy On-Premise offers two license tiers. Both are signed offline with ML-DSA-65 (NIST FIPS 204) — the license file itself proves its own authenticity, with no network call back to FIPSign required to validate it.

Requesting a trial

Go to onprem.fipsign.dev/trial and submit your company name and email. A few things to know before you do:

• Corporate email required. Free email providers (Gmail, Outlook.com, Yahoo, etc.) are not accepted — use your company's own domain.
• One active trial per email domain every 30 days. If your company already requested a trial recently, a new one for the same domain won't be issued until that window passes.
• You'll receive a confirmation email — click the link to verify your email and get your license file. The link is single-use and expires after a period; if it's expired or already used, request a new trial.

Buying a Standard license

Go to onprem.fipsign.dev/purchase. The flow has an extra step compared to the trial, by design:

1. Submit your company name and email.
2. Click the confirmation link sent to that email. This locks in the exact email your license will be tied to before any payment happens — so a typo in the address can't send a paid license somewhere you don't control.
3. You're redirected to Dodo Payments to complete payment (card or crypto).
4. Once payment is confirmed, your license file and download link arrive by email — usually within minutes.

Didn't receive the email?

Go to onprem.fipsign.dev/recover (also linked in the footer of every page on the site) and enter the email you used. If it has any active, non-expired licenses — trial or standard — you'll receive a fresh download link for each of them in a single email. This also works months later, if you've simply lost your license.pqp file and need to recover it again.

02 Installation

Copy your license file to the server, then run one command. The installer downloads everything it needs, asks a series of configuration questions, and starts the stack.

scp license.pqp root@YOUR_SERVER_IP:/root/

curl -fsSL https://proxyonprem.fipsign.dev/install -o install.sh && bash install.sh

What the installer asks

Every question has a sensible default (shown in brackets) — press Enter to accept it.

After it finishes

The installer prints your admin token once — copy it immediately, it's never shown again. It looks like pqp_onprem_<random>. You'll use it to log into the dashboard for the first time (covered in Section 03 — First login & admin token).

Your dashboard is now reachable at http://YOUR_SERVER_IP:9090/dashboard.

03 First login & admin token

There's no username/password to set up. The admin token the installer printed is your credential — open the dashboard, paste it in, and you're in.

1. Go to http://YOUR_SERVER_IP:9090/dashboard.
2. Paste the pqp_onprem_... token you copied when the installer finished.
3. You're logged in — a session cookie keeps you signed in for the duration you set during install (default 24 hours).

Rotating the token

Once logged in, you can generate a new admin token at any time from the dashboard (Settings → Rotate admin token) — useful if you suspect the current one was exposed, or as routine hygiene. Rotating it immediately invalidates the old one. Same rule applies: the new token is shown once, copy it right away.

Recovering access

If you never logged in and lost the token, there's no self-service "forgot password" flow through the dashboard or email — by design, this system doesn't depend on any internet connection for account recovery, since it's meant to work fully offline. Instead, run this on the server itself, over SSH, as root:

docker compose exec api pq-proxy-api reset-token

This requires no dashboard access, no active session, and no database knowledge — just SSH to the server. It generates a new token, invalidates the old one immediately, and prints the new token to your terminal in the same format as the very first install. Copy it and log in as usual.

Invalidating all sessions

If you believe someone else may have an active dashboard session (for example, after rotating the token because it leaked), Settings → Invalidate all sessions immediately logs out every other active session — the one you're using right now to click the button stays logged in, so you're never interrupted by your own action.

04 Managing domains

Each domain you add tells PQ-Proxy: "when a visitor connects for this hostname, forward the traffic to this backend." Add domains from Dashboard → Domains → + Add domain.

Editing, disabling, and deleting

Any change to a domain's backend, port, TLS setting, or CA certificate — as well as disabling or deleting it — immediately cuts any connection already in progress for that domain. There's no grace period: a visitor mid-connection when you save the change gets disconnected, and reconnects fresh against whatever is configured now. Re-enabling a domain doesn't cut anything, since nothing was being served for it a moment before.

05 TLS certificates (BYOC)

PQ-Proxy has a single certificate mechanism: bring your own certificate (BYOC). There's no automatic certificate issuance — you upload a certificate and private key for each domain, and PQ-Proxy serves exactly what you gave it.

Upload from Dashboard → Certificates, or from a domain's own settings:

What gets validated on upload

Before anything is saved, PQ-Proxy checks, in order:

1. Both fields are valid PEM with the expected markers.
2. Both parse as a valid X.509 certificate and a valid private key.
3. The certificate and the private key are an actual matching pair — their public keys are compared directly. A mismatched cert/key pair for a domain is a common mistake and is rejected outright, with a clear error, rather than silently stored and failing at connection time.
4. The certificate isn't already expired.
5. The certificate has already started being valid (its "not before" date isn't in the future).
6. The certificate's SAN (Subject Alternative Name) actually covers this domain — uploading a certificate issued for a different domain is rejected, not silently accepted. A single-level wildcard (*.example.com) correctly covers a.example.com but not a.b.example.com, matching how wildcard certificates actually work.

Any failure returns a specific error explaining which check failed — nothing partial is ever saved.

Storage

The private key is encrypted at rest with CERT_ENCRYPTION_KEY (generated automatically during install — see Section 02) before being stored in the database.

Replacing or removing a certificate

Uploading a new certificate for a domain that already has one simply replaces it — same validation, same effect as a first upload. Deleting a certificate leaves the domain with none until you upload a replacement; nothing is issued automatically to fill the gap.

06 Verifying post-quantum TLS

Before checking anything, know what to expect: not every connection to your domain will be post-quantum. PQ-Proxy negotiates it when the connecting client supports it, and falls back to classical X25519 — standard TLS 1.3 behavior — when it doesn't. Older browsers, some HTTP client libraries, and various automated tools don't support it yet. This is expected, not a misconfiguration.

From a browser

Chrome and Firefox (recent versions) support X25519MLKEM768. Open DevTools → Security tab (Chrome) while loading your domain, and check the key exchange group listed for the connection — it should say X25519Kyber768Draft00 or X25519MLKEM768 depending on the browser version.

From the command line

With OpenSSL 3.5 or later (which added native ML-KEM support):

openssl s_client -connect your-domain.com:443 -groups X25519MLKEM768 </dev/null

Look for Negotiated TLS1.3 group: in the output — it should show the post-quantum group, not plain X25519.

From your own connection logs

This is the most reliable way to check real traffic, not just your own test connection — every connection PQ-Proxy handles is logged with the key exchange group it actually negotiated, per connection. Go to Dashboard → Metrics, or query the connection log export directly (Section 13) and filter by domain to see the real mix of post-quantum vs. classical connections your visitors are using.

07 License states & limits

Your license has one of four states at any given time, checked when the license file is loaded — at startup, and every 30 minutes afterward. The proxy's behavior depends entirely on this state, not on anything else.

Where to check your current state

Dashboard → Overview shows a badge for the current state at a glance, and Dashboard → License shows the full detail — days remaining, domain usage, and tier.

08 Recovering a lost license

If you lost your license.pqp file — deleted it, migrated servers without backing it up, or never received the original email — you don't need to contact support. Recovery is entirely self-service.

Go to onprem.fipsign.dev/recover (linked in the footer of every page on the site) and enter the email you originally used — whether that was for a trial or a paid license.

What you'll get

If that email has any active, non-expired licenses — trial or standard, any number of them — you'll receive a single email with a download link for each one. A license that already expired, or was revoked, won't appear; there's nothing useful to recover there.

This also works months later

The download link never expires and can be reused — recovery isn't limited to right after you lose it. If you're setting up a replacement server six months after your original install, the same flow gets you your license.pqp file again.

09 Webhook alerts

PQ-Proxy can notify you proactively when something needs attention — no need to check the dashboard yourself. Configure a webhook URL during install (or later, via --reconfigure), and PQ-Proxy POSTs a JSON payload to it whenever one of the events below fires.

Events

Payload & verifying authenticity

Every payload shares the same envelope — only data changes per event:

{
  "event": "cert_expiry_warning",
  "timestamp": "2026-09-22T14:30:00Z",
  "instance": "your-company-name",
  "data": { ...see below... }
}

data for license_expiry_warning, license_expiry_critical, and license_expired:

{
  "tenant": "your-company-name",
  "tier": "standard",
  "expires_at": "2026-10-15T00:00:00Z",
  "days_remaining": 5
}

data for cert_expiry_warning and cert_expiry_critical:

{
  "domain": "api.yourcompany.com",
  "expires_at": "2026-10-01T00:00:00Z",
  "days_remaining": 6,
  "cert_source": "byoc"
}

data for backend_unhealthy:

{
  "domain": "api.yourcompany.com",
  "consecutive_failures": 3,
  "last_error": "connection refused"
}

data for backend_recovered:

{
  "domain": "api.yourcompany.com"
}

The request includes an X-PQProxy-Event: alert header, and — if you set a webhook secret during install — an X-PQProxy-Signature: sha256=<hex> header, an HMAC-SHA256 of the raw request body using that secret. Verify it on your receiving end to confirm the request genuinely came from your instance. The timestamp field lets you additionally reject old, replayed requests — a 5-minute window is a reasonable default.

10 Backend health

Every 60 seconds, PQ-Proxy checks connectivity to each of your active domains' backends — a real TCP connection attempt (and a full TLS handshake, if the domain has Backend speaks TLS enabled). The result is what you see as a badge next to each domain in Dashboard → Domains.

Relationship to webhook alerts

This badge and the backend_unhealthy / backend_recovered webhooks (Section 09) come from the exact same underlying check — the badge is a passive read of the current state, the webhook is what proactively notifies you when the state changes. A domain can show 🔴 without having triggered a webhook yet: the webhook only fires after 3 consecutive failures (roughly 3 minutes of sustained downtime), while the badge turns red on the very first failed check.

11 Prometheus metrics

If you enabled Prometheus during install (Section 02), management-api exposes metrics in standard Prometheus text format at GET /metrics — no authentication, since this endpoint listens on port 9091, internal to the Docker network and never mapped to the host by default.

services:
  api:
    ports:
      - "9091:9091"

Then docker compose up -d to apply it. Once exposed, add a scrape target for YOUR_SERVER_IP:9091 in your Prometheus config.

What the raw response looks like

Unlike webhooks, there's no event that gets pushed to you — Prometheus (or you, with a browser) fetches /metrics whenever it wants, and gets back the current value of every metric, every time. A few real lines from the response, so you know what to expect:

# HELP pqproxy_connections_24h Connections in the last 24 hours
# TYPE pqproxy_connections_24h gauge
pqproxy_connections_24h{domain="api.yourcompany.com"} 1543

# HELP pqproxy_cert_expires_days Days until TLS certificate expiry
# TYPE pqproxy_cert_expires_days gauge
pqproxy_cert_expires_days{domain="api.yourcompany.com",source="byoc"} 47

Each metric has a # HELP line (a description) and a # TYPE line (counter for values that only go up, like total connections; gauge for values that can go up or down, like days until expiry), followed by one line per value. When a metric has more than one label — like pqproxy_connections_by_algorithm_total, which reports by both domain and algorithm — you'll see a separate line for each combination that has data.

Available metrics

Instance

Per domain — traffic (label domain)

Per domain — post-quantum adoption (labels domain, algorithm)

Per domain — latency & certificates (label domain)

12 Audit log

Every sensitive action taken on this instance — through the dashboard or the API — is recorded in an audit log: Dashboard → Audit log, paginated (25 per page).

Exporting

Dashboard → Audit log → Export CSV, with optional from/to/action filters. Same row limit and truncation behavior as the connection log export (see Section 13) — up to 10,000 rows per request, with an X-Export-Truncated: true header if there's more.

13 Connection logs & export

Every connection PQ-Proxy handles is logged: domain, source address, bytes transferred, negotiated algorithm, and timing (TLS handshake, backend connect, total duration). This is the source of truth behind the Metrics dashboard and behind verifying real post-quantum adoption (Section 06).

Exporting

Dashboard → Metrics → Download CSV, with optional From/To/Domain filters.

Retention

Connection logs are kept for the number of days set during install (Section 02, default 30). A background worker checks every 24 hours and deletes anything older than that — so purging isn't instant the moment a log crosses the threshold, it happens on the next daily pass. Export anything you need to keep before it ages out.

14 Software updates

There are two independent, unrelated ways this instance can check for a new version — knowing the difference matters, since only one of them actually surfaces anything to you directly.

What you actually see: the dashboard banner

Every time you open Dashboard → Overview, it asks GET /api/v1/updates/check, which reaches out to FIPSign's release feed on the spot and compares it to your running version. If a newer one exists, a banner appears with a link to the release notes. This is the check you'll actually notice.

A separate background check: logs only, no banner, no webhook

Independently, if Check for updates automatically? was enabled during install (Section 02), a background worker performs this same comparison on its own schedule (default every 24 hours) — but it only ever writes the result to the container's own logs (docker compose logs api). It does not show a dashboard banner, and it does not send a webhook alert. If you want to be notified without having to open the dashboard yourself, you'd need to watch these logs externally — there's no built-in push notification for this today.

Updating

Pull the newer images and restart the stack:

docker compose pull && docker compose up -d

Your domains, certificates, and license file are untouched by an update — only the container images change.

15 Reconfiguration

To change any setting after the initial install — a port, the webhook URL, log retention, and so on — run the installer again with --reconfigure:

curl -fsSL https://proxyonprem.fipsign.dev/install -o install.sh && bash install.sh --reconfigure

This isn't "start over" — it's closer to editing an existing configuration. Most questions are asked again with your current value pre-filled as the default — press Enter to keep it, or type a new value to change it. A few fields behave differently, worth knowing before you run it:

16 Management API reference

Every endpoint below is served by management-api on port 9090. All responses share the same envelope: {"{"}"success": bool, "data": ..., "error": string | null{"}"}. Click any endpoint to see its exact request and response shape.

Authenticating requests

Every "Main" and "Admin" endpoint below needs either a logged-in dashboard session (the cookie your browser already holds) or a Bearer token — the same admin token you log into the dashboard with, no separate API key or token exchange step. For scripts and programmatic access, send it as an Authorization header:

curl https://YOUR_SERVER_IP:9090/api/v1/domains \
  -H "Authorization: Bearer pqp_onprem_your_token_here"

Auth — no authentication required

{ "token": "pqp_onprem_..." }

{ "authenticated": true }

{ "authenticated": true, "instance_name": "your-company-name" }

Main — session cookie or Bearer admin token

{
  "name": "your-company-name",
  "edition": "onprem",
  "version": "1.0.5",
  "license_tier": "standard",
  "license_status": "valid",
  "max_domains": 0,
  "domain_count": 3
}

{
  "id": "b7e6...",
  "domain": "api.yourcompany.com",
  "backend_host": "10.0.1.5",
  "backend_port": 8080,
  "backend_tls": false,
  "active": true,
  "created_at": "2026-01-15T00:00:00Z",
  "cert_updated_at": "2026-06-01T00:00:00Z",
  "backend_ca_cert": null
}

{
  "domain": "api.yourcompany.com",
  "backend_host": "10.0.1.5",
  "backend_port": 8080,
  "backend_tls": false,
  "backend_ca_cert": null
}

{
  "backend_host": "10.0.1.6",
  "backend_port": 8080,
  "backend_tls": true,
  "backend_ca_cert": "-----BEGIN CERTIFICATE-----..."
}

{
  "domain": "api.yourcompany.com",
  "cert_source": "byoc",
  "expires_at": "2026-12-01T00:00:00Z",
  "obtained_at": "2026-09-01T00:00:00Z",
  "chain_complete": true
}

{
  "cert_pem": "-----BEGIN CERTIFICATE-----...",
  "key_pem": "-----BEGIN PRIVATE KEY-----...",
  "intermediate_pem": "-----BEGIN CERTIFICATE-----..."
}

{
  "license_key": "PQP-STD-...",
  "tenant": "your-company-name",
  "tier": "standard",
  "max_domains": 0,
  "max_instances": 1,
  "features": ["byoc", "prometheus", "webhook_alerts"],
  "status": "valid",
  "days_remaining": 210,
  "expires_at": "2027-06-15T00:00:00Z",
  "verified_at": "2026-09-22T10:00:00Z",
  "domain_count": 3
}

{
  "current_version": "1.0.5",
  "latest_version": "1.0.6",
  "update_available": true,
  "release_url": "https://github.com/.../releases/tag/v1.0.6",
  "check_enabled": true
}

{
  "id": "9c2f...",
  "action": "domain_updated",
  "resource_type": "domain",
  "resource_id": "b7e6...",
  "metadata": { "active": false },
  "ip_addr": "203.0.113.4",
  "created_at": "2026-09-22T14:00:00Z"
}

{
  "domain": "api.yourcompany.com",
  "connections_24h": 1543,
  "connections_7d": 9821,
  "connections_30d": 41209,
  "pq_connections_24h": 1102,
  "pq_connections_7d": 6890,
  "pq_connections_30d": 27904,
  "bytes_sent_total": 8912340192,
  "bytes_recv_total": 40129384021
}

{
  "domain": "api.yourcompany.com",
  "tls_p50_ms": 12.4,
  "tls_p95_ms": 28.1,
  "tls_p99_ms": 45.0,
  "backend_p50_ms": 3.2,
  "backend_p95_ms": 9.8,
  "backend_p99_ms": 15.6,
  "sample_count": 1543
}

{
  "domain": "api.yourcompany.com",
  "is_healthy": true,
  "status": "healthy",
  "latency_ms": 42,
  "last_checked_at": "2026-09-22T14:00:00Z",
  "last_error": null,
  "consecutive_failures": 0
}

Admin — session cookie only, Bearer token not accepted

{ "token": "pqp_onprem_...", "message": "Save this token — it will not be shown again." }

{ "sessions_revoked": 2, "message": "..." }