Edge Core

Self-hostable control plane for distributed Linux and Edge fleets — WireGuard mesh, SSH proxy, remote execution, Prometheus metrics, events, and MCP over one API.

📖 Docs: wenet-ec.github.io/edge-core

Edge Core manages Linux machines you do not physically touch: cloud VMs, on-premises servers, factory equipment, Raspberry Pis, homelab boxes, and IoT devices. It gives operators one place to connect to, observe, and operate those machines without exposing every host to the public internet.

The name comes from our original edge-device use case, but edge means any machine that is remote from the operator. A VM in Frankfurt and a Raspberry Pi in a factory present the same control-plane problem; the difference is how hostile and unreliable the surrounding network can be.

The edge version of a cloud control plane

Cloud providers made centralized machine management familiar: private networking, metrics, remote execution, SSH, updates, events, and automation APIs. Edge Core applies those same control-plane ideas to machines distributed across sites the operator does not fully control.

The edge difference is the network and failure model: NAT, firewalls, UDP filtering, intermittent links, changing addresses, local-only services, and power outages. Edge Core treats resilient connectivity as part of the control plane instead of assuming it already exists.

Edge Core manages machines that already exist; it is not a general-purpose compute, storage, or region provider. The self-hostable Core is platform-agnostic. A hosted platform can add provisioning, deployment packages, tenancy, billing, and other cloud-style services above it without changing the Core contract.

What it does

• Remote command execution — run shell commands across selected nodes and collect each result independently.
• Centralized SSH — manage usernames and public keys centrally, then reach nodes through the Admin proxy without exposing port 22.
• Metrics aggregation — collect host, Agent, and WireGuard metrics through Prometheus-compatible discovery and endpoints.
• Self-updates — coordinate Agent updates across a fleet from one API request.
• VPN connectivity — create isolated WireGuard meshes per cluster, with relay fallback for difficult NAT paths.
• Proxying — tunnel HTTP or arbitrary TCP traffic through a node, including access to that node's local network.
• Lifecycle events — publish CloudEvents through signed webhooks or a message broker instead of polling.
• AI operations — expose the REST management surface through MCP for compatible assistants and automation.

Who is it for?

Edge Core is a good fit when you need to:

• manage Linux machines across factories, stores, offices, vehicles, homes, or multiple clouds;
• operate hosts behind NAT or firewalls without exposing SSH and application ports;
• collect metrics centrally without giving the monitoring system direct access to every node;
• automate fleet work while retaining per-node output, status, and lifecycle events; or
• self-host the control plane and build higher-level workflows on its API.

It is intentionally general Linux infrastructure management, not an operating system or device-management lock-in layer. Ansible, Tailscale/Headscale, cloud providers, and existing monitoring systems can complement it; Edge Core focuses on the connectivity and operational control plane between them.

Architecture

Cloud or self-hosted control plane
├── Edge Admin (one or more peers)
│   ├── REST API, OpenAPI, MCP, events, and metrics
│   ├── Cluster ownership and background operations
│   └── HTTP + SOCKS5 forward proxies
├── PostgreSQL (standard) or SQLite (lite)
└── Netmaker VPN stack

Distributed machines
└── Edge Agent (one per machine)
    ├── WireGuard netclient
    ├── Embedded SSH server and command execution
    ├── HTTP + SOCKS5 proxy
    └── Metrics exporters and diagnostics

Admin and Agent communicate over WireGuard when possible, fall back to DERP relay when direct UDP paths fail, and retain HTTP polling for eventual control during VPN outages. For the full design, see docs/architecture.md.

Getting started

Everything runs through Docker Compose; no Elixir or Go installation is required on the host.

Each setup guide covers requirements, configuration, first enrollment, and upgrades. After starting Admin, use the operator guide, the live / guide, and /swaggerui for day-to-day work.

Compatibility and deployment notes

Admin is a containerized deployment target. Agent is a privileged, host-networked container and therefore depends on the host's networking, resolver, container runtime, and WireGuard support. Tested Agent hosts currently include Ubuntu 24.04/26.04, Debian 13, Rocky Linux 10 and RHEL-family hosts, and Alpine 3.24.

See the operator guide for host-specific notes, including firewalld, and the example guides for deployment requirements. The full architecture and operational contracts live in docs/architecture.md.

Useful references

• User and operator guide
• Architecture
• OpenAPI reference
• AsyncAPI event catalog
• MCP tool catalog
• Lite deployment
• Standard deployment
• Relay deployment
• Sidecar deployment
• Contributing

Components

License

Edge Core ships under multiple licenses; see LICENSE for the complete terms.

You may self-host, modify, and use Edge Core internally or as part of your own services. The Elastic License restricts offering Edge Admin itself, or a thin wrapper around it, as a hosted service to third parties. Contact [email protected] if your use case needs clarification or a commercial license.

Contributions are welcome. See CONTRIBUTING.md for the contribution flow and DCO requirements.