Skip to content
Edgible Docs

Devices — gateway and serving

A device in Edgible is any machine running the agent. Every device has a single role — gateway or serving — chosen at install time. The two roles cooperate to deliver a request from the public internet to one of your workloads.

Serving devices

Section titled “Serving devices”

A serving device is your hardware, running your workloads. It’s the machine you install the agent on. It runs:

  • The Edgible agent — a Node.js process that maintains a WebSocket connection to the control plane and reconciles desired application state.
  • A WireGuard interface — one per organization, joining the device to a private network shared with the gateway.
  • A Caddy reverse proxy — listens locally on the WireGuard interface, terminates TLS, enforces auth policies, and proxies to your workloads.
  • The workloads you’ve declared — Docker Compose stacks, single containers, managed processes, VMs, or pre-existing services.

A serving device never accepts inbound connections from the public internet. The only network requirement is outbound TCP/443 to the Edgible control plane and outbound UDP to the gateway over WireGuard.

You run as many serving devices as you want, in as many locations as you want. They all share one organization-wide WireGuard subnet (the device pool).

Gateway devices

Section titled “Gateway devices”

A gateway device is the public-facing edge. It runs:

  • The Edgible agent (same binary as serving, but configured for gateway mode).
  • A WireGuard interface that pairs with each serving device’s interface.
  • An HAProxy instance that listens on TCP/443 (and optionally TCP/80) on the public IP, inspects SNI, and forwards encrypted streams to the right serving device over the appropriate tunnel.
  • Optional protocol-specific listeners for raw TCP and UDP services.

By default, you don’t run a gateway. Edgible operates a managed gateway pool — when you deploy your first application, the platform assigns one to your organization, configures HAProxy with the routes you’ve declared, and starts forwarding. You see this as a deploying_gateway step in edgible stack status.

If you have a reason to run your own gateway — for example, you want public traffic terminating in a specific cloud account — edgible gateway create is available. For most users, the managed default is the right choice.

Choosing the role at install time

Section titled “Choosing the role at install time”

You set the role with --device-type when installing:

Terminal window
sudo edgible agent install --device-type serving --device-name my-first
sudo edgible agent install --device-type gateway --device-name eu-gateway

The role cannot be changed after installation. Uninstall and reinstall if you need to switch.

How they discover each other

Section titled “How they discover each other”

Devices in the same organization see each other through the device pool — a per-organization WireGuard subnet (e.g., 10.42.0.0/16). When a new device registers:

  1. The control plane allocates it an IP in the pool.
  2. The control plane pushes the new device’s WireGuard public key and IP to every other device in the same pool.
  3. Each peer adds the new device to its own WireGuard configuration.

Within a few seconds of edgible agent start, every other device in your organization can route packets to the new device over the encrypted tunnel. Device-to-device traffic never leaves the WireGuard mesh.

Device pools and WireGuard goes deeper on the mesh topology.