Knocker is a configurable, and self-hosted service that provides an HTTP based "knock-knock" single-packet authorization (SPA) gateway for your Homelab with web, cli and android clients. it can be used as authentication for your reverse proxy like Caddy, or even on the firewall level using the FirewallD integration. It allows you to keep your services completely private, opening them up on-demand only for authorized IP addresses.
This is ideal for homelab environments where you want to expose services to the internet without a persistent VPN connection, while minimizing your public-facing attack surface.
Sequence diagram
sequenceDiagram participant User participant Caddy as Reverse Proxy (Caddy) participant Knocker participant Service as Protected Service User->>Caddy: HTTP request to protected service Caddy->>Knocker: GET /verify (copies X-Forwarded-For) Knocker-->>Knocker: check always_allowed_ips / excluded_paths / whitelist alt IP whitelisted Knocker-->>Caddy: 200 OK (empty body) Caddy->>Service: forward request Service-->>Caddy: 200 OK Caddy-->>User: 200 OK else IP not whitelisted Knocker-->>Caddy: 401 Unauthorized (empty body) Caddy-->>User: 401 Unauthorized end Note over User,Knocker: Performing a "knock" (to add whitelist entry) User->>Knocker: POST /knock (X-Api-Key, optional ip_address, ttl) Knocker->>Knocker: validate API key, determine client IP Knocker->>Knocker: update whitelist.json with expiry Knocker-->>User: 200 OK (whitelisted_entry, expires_at, expires_in_seconds) Loading
Features
API Key Authentication : Secure your knock endpoint with multiple, configurable API keys.
: Secure your knock endpoint with multiple, configurable API keys. Configurable TTL : Each API key can have its own Time-To-Live (TTL), defining how long a whitelisted IP remains active.
: Each API key can have its own Time-To-Live (TTL), defining how long a whitelisted IP remains active. Remote Whitelisting : Grant specific admin keys permission to whitelist any IP or CIDR range, not just their own.
: Grant specific admin keys permission to whitelist any IP or CIDR range, not just their own. Static IP/CIDR Whitelisting : Always allow certain IP addresses or ranges to bypass the dynamic whitelist.
: Always allow certain IP addresses or ranges to bypass the dynamic whitelist. Path-Based Exclusion : Exclude specific URL paths (like health checks or public APIs) from authentication entirely.
... continue reading