How it works

Edgible has two parts: a public-facing edge that Edgible operates, and a device — hardware you own — that hosts your workload. A public request traverses both parts.

The two parts

The edge is Edgible-operated infrastructure: HAProxy listening on a public IP, terminating TCP, looking at the SNI hostname, and forwarding the encrypted stream over a WireGuard tunnel to whichever device hosts the application for that hostname. You don’t run any of it; Edgible does.

The device runs the agent, a Caddy reverse proxy, a WireGuard interface that pairs with the edge, and the workloads you’ve declared. It never accepts inbound connections from the public internet — its only network requirement is outbound HTTPS to the Edgible control plane and outbound UDP for the WireGuard tunnel.

You install the agent on hardware you own and target it with placement.strategy: serving-device.

The path of a request

Public Internet
       │
       ▼
Edgible-managed edge  (HAProxy + WireGuard)
       │  (encrypted WireGuard tunnel)
       ▼
Device hosting the application  (your hardware, 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 edge node. HAProxy sees the SNI api.example.com, looks up which device owns that hostname, and forwards the byte stream over the WireGuard tunnel. On your 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 sees a normal HTTP request and responds. The response flows back the same way.

Why this shape

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

1. No inbound exposure on your hardware. A 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. One model, every device. The same YAML deploys to any device you own. You can run many devices within an organization, and applications can be migrated between them.
4. Movability. A 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. For applications with mobility: movable storage, the workload itself can move between devices.

The control plane

Separately from the data plane above, the agent on each 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.

Migration between devices is also coordinated here: a multi-phase workflow (preflight → quiesce → snapshot → ship → restore → cutover) runs against the same agents and the same control plane.

Read on: Devices covers what’s running on a device. Device pools and WireGuard explains how the tunnels are addressed.