How it works

Edgible has two kinds of devices, and a request travels through both of them.

The two device roles

A serving device is yours. It’s a machine you own — physical or virtual, Linux — that runs the Edgible agent, the workloads you’ve declared, a Caddy reverse proxy, and a WireGuard network interface. A serving device never accepts inbound connections from the public internet. The only network it needs is outbound HTTPS so the agent can reach the Edgible control plane.

A gateway device is the public-facing entry point. By default it’s run and operated by Edgible — you don’t provision it. The gateway runs HAProxy and a WireGuard interface that pairs with your serving device’s interface, forming a private encrypted tunnel between the two. The gateway terminates the public TCP connection, looks at the SNI hostname, and forwards the encrypted stream over the tunnel to whichever serving device owns that hostname.

The path of a request

Public Internet
       │
       ▼
Edgible-managed Gateway (HAProxy + WireGuard)
       │  (encrypted WireGuard tunnel)
       ▼
Your Serving Device
       │
       ├── Caddy  (TLS termination, auth enforcement)
       │
       ▼
Your Workload  (container, process, or VM)

A user types https://api.example.com in a browser. DNS resolves to the public IP of an Edgible gateway. HAProxy on the gateway sees the SNI api.example.com, looks up which serving device owns that hostname, and forwards the byte stream over the WireGuard tunnel. On the serving device, Caddy terminates TLS using a certificate Edgible has already provisioned, checks any access policy you’ve configured (organization membership, API key, short code), and proxies the request to your workload’s local port. The workload — your container, your binary, whatever you declared — sees a normal HTTP request and responds. The response flows back the same way.

Why this shape

Three properties fall out of this design that you’d otherwise have to build yourself:

1. No inbound exposure on your hardware. Your serving device’s IP never appears in DNS, never receives unsolicited packets, never needs port-forwarding rules on your home router or VPC firewall.
2. TLS that just works. Certificates are provisioned by the platform, stored in the agent’s local config, rotated automatically, and applied by Caddy without you touching a config file.
3. Movability. A serving device is identified by its WireGuard key and its agent identity, not its IP. You can move the machine across networks and the public hostname still points to it once it reconnects.

The control plane

Separately from the data plane above, the agent on each serving device maintains a WebSocket connection to the Edgible API. This is how desired state gets pushed to the device — when you edgible stack deploy, the agent receives an application_update message within a second or two, reconciles it (starts containers, writes Caddy config, requests a cert if needed), and reports back. Health, logs, and lifecycle events flow over the same channel.

Read on: Devices goes deeper on the gateway/serving distinction. Device pools and WireGuard explains how the tunnels are addressed.