Edge architecture and operations

​

Goal

​

Prerequisites

• Read the Compute edge network overview for the customer-facing entry points.

​

Workflow

​

Components and traffic

• The Compute host has a dedicated sscompute0 WireGuard interface to the shared edge. It is separate from libvirt, the Compute runner, and the older shared IPv4 gateway.
• For SSH, the edge listens on the VPS’s allocated public TCP port and forwards raw SSH traffic over the overlay to the host relay. The host relay opens a connection to the selected guest SSH port. The guest SSH daemon still handles login and host keys.
• For web, Caddy receives HTTPS and selects a registered hostname. A local edge HTTP relay forwards across the overlay to the host relay, which connects to the selected guest HTTP port. The guest receives the request using the published Host name.
• The compute host uses an existing host-reachable guest address. No guest agent, virtual NIC change, DHCP change, or libvirt restart is part of publishing.

​

Isolation and ownership

• Customer operations are authorized against the owner of the Compute instance. A hostname label is reserved to its first VPS, a custom hostname to its account, and an allocated SSH edge port to its first VPS. Removing a route does not allow a stale name or port to reach a different tenant.
• The node reconciler accepts routes for its own node and validates guest target addresses and ports. Its dedicated relay process is firewall-restricted to the address/port pairs in the active snapshot; the overlay ingress permits only the edge peer and needed listener ports.
• The edge applies optional client CIDR rules for web routes and SSH endpoints. No CIDR list means public access. CIDR restrictions control entry to the edge, not the guest’s other direct public addresses.
• Each publication targets one selected port. It does not broadly open all VPS ports or alter any firewall rules the customer has set inside the guest.

​

Reconciliation and status

• The control plane stores desired web routes, verified domains, SSH allocations, and an increasing revision. Compute-host and edge reconcilers fetch their snapshots, apply them, and acknowledge the revision independently.
• The edge does not publish a route until the owning compute host has acknowledged the relevant revision. The UI shows configured only after both sides have acknowledged it. A queued change can remain pending while either side catches up.
• Only eligible, running VPSs are included in active snapshots. Stopped, suspended, rescue-enabled, and deleted instances are excluded. Their direct workload state is governed by the normal Compute lifecycle.
• The relay reloads the snapshot and closes sessions on changed or removed routes. The edge checks the full Caddy configuration before reload and restores its previous generated fragment if applying a change fails.
• An edge health probe samples published StackShift subdomains at /. A below-500 HTTP response reports healthy; it is a reachability signal, not a full application-specific health check.

​

Failure and recovery boundaries

• If the Compute publishing route or relay is unavailable, that published HTTPS hostname or Edge SSH endpoint fails while the VPS and its direct IP paths remain available. A host-wide outage of the shared edge can also affect other services running on that host, including older gateway mappings.
• If the guest app or SSH daemon is down, a configured edge route cannot make it healthy. Check the service and selected port inside the guest after confirming the edge path.
• The overlay and relays reconcile desired state after service restarts. Revocation and restoration depend on reconciliation completing; do not assume a route change is instantaneous.
• The existing shared IPv4 gateway is not the Edge SSH allocator. Shared outbound IPv4 connectivity does not automatically provide an inbound SSH endpoint for every IPv6-only VPS.

​

Expected result

​

Common failures

​

Related guides