wild-central/docs/registrations.md

Service Registrations

Wild Central provides DNS, proxy routing, TLS, and DDNS for services on the LAN. External consumers (Wild Cloud, Wild Works) register their domains with Central's API, and Central handles the networking.

Registration API

POST   /api/v1/services              Register a domain
GET    /api/v1/services              List all registrations
GET    /api/v1/services/{domain}     Get registration details
PATCH  /api/v1/services/{domain}     Update a registration
DELETE /api/v1/services/{domain}     Remove a registration
DELETE /api/v1/services/deregister?source=X&backend=Y   Batch cleanup

The domain is the unique key. One registration per domain.

Fields

Field	Type	Required	Default	Description
domain	string	yes	—	FQDN to route. Unique key.
source	string	no	"manual"	Who registered this: wild-cloud, wild-works, manual.
backend.address	string	yes	—	Target host:port (e.g., 192.168.8.240:443).
backend.type	string	yes	—	tcp-passthrough or http.
backend.health	string	no	—	Health check path for L7 services (e.g., /health).
subdomains	bool	no	false	If true, also routes *.domain traffic to this backend.
reach	string	yes	—	internal or public.
tls	string	no	inferred	passthrough or terminate. Defaults based on backend type.

User-facing concepts

The API fields map to three user-visible controls:

Public / Private

reach: "public" or reach: "internal"

• Private (internal): Domain resolves only on the LAN. No public DNS record. Accessible only from your local network or VPN.
• Public: Domain resolves on the LAN AND has a public DNS A record. Accessible from the internet through Central's HAProxy.

Subdomains

subdomains: true or subdomains: false

• Off (default): Only the exact domain is routed (payne.io routes, but foo.payne.io does not).
• On: Both the domain and all subdomains are routed (cloud.payne.io AND matrix.cloud.payne.io, vaultwarden.cloud.payne.io, etc.).

TLS handling

tls: "passthrough" or tls: "terminate"

• Passthrough: Central forwards encrypted traffic directly to the backend. The backend handles its own TLS certificates (e.g., a k8s cluster with traefik). Maps to backend.type: "tcp-passthrough".
• Terminate: Central provisions a TLS certificate and handles HTTPS. Traffic is decrypted at Central and proxied as HTTP to the backend. Maps to backend.type: "http".

What Central does per registration

When a service is registered, Central automatically:

Effect	Passthrough	Terminate
LAN DNS	address=/<domain>/<backend-IP> — direct to backend	address=/<domain>/<central-IP> — through Central
LAN DNS (private)	Also local=/<domain>/ — prevents upstream forwarding	Same
Public DNS	DDNS A record if public	Same
Proxy	L4 SNI passthrough. Subdomains adds *.domain matching.	L7 HTTP reverse proxy by Host header.
TLS	Backend handles — Central passes through	Central provisions cert via Let's Encrypt

Examples

k8s cluster (passthrough, public, with subdomains)

{
  "domain": "cloud.payne.io",
  "source": "wild-cloud",
  "backend": {"address": "192.168.8.240:443", "type": "tcp-passthrough"},
  "subdomains": true,
  "reach": "public"
}

Central creates: LAN DNS → 192.168.8.240, public DNS A record, HAProxy L4 SNI + wildcard *.cloud.payne.io, TLS passthrough.

Internal web app (terminate, private)

{
  "domain": "wild-cloud.payne.io",
  "source": "wild-cloud",
  "backend": {"address": "127.0.0.1:5055", "type": "http"},
  "reach": "internal"
}

Central creates: LAN DNS → Central IP (with local=/), HAProxy L7 reverse proxy, TLS cert via certbot. No public DNS.

Custom domain (passthrough, public, exact match)

{
  "domain": "payne.io",
  "source": "wild-cloud",
  "backend": {"address": "192.168.8.240:443", "type": "tcp-passthrough"},
  "subdomains": false,
  "reach": "public"
}

Central creates: LAN DNS → 192.168.8.240, public DNS A record, HAProxy L4 SNI exact match only. No wildcard.

What is NOT a registration

Central's own services come from config, not the registration API:

• Central's UI domain (cloud.central.domain)
• VPN (cloud.vpn.*)
• Firewall rules (cloud.nftables.*)
• DHCP (cloud.dnsmasq.dhcp.*)
• CrowdSec, certbot credentials, DDNS provider config