Aegis

Run AI on hardware you control.

One control plane from the bare metal up — provisioning, networking, Kubernetes, models and serving.
Fully air-gapped when you need it. Your model weights stay on your storage.
With an AI operator that does the routine work instead of describing it.

aegis.jerxie.com — ask the assistant anything about the platform

---

---

What Aegis is

Every organisation that cannot put its data in someone else's cloud currently assembles an on-prem AI stack out of six tools — a mesh VPN, an ingress gateway, a Kubernetes distribution, a bare-metal provisioner, an artifact registry, a monitoring stack — plus a team to keep them in step. That team is the product they are actually buying, and it does not scale.

Aegis replaces the assembly. One hub container runs the control plane; a single agent enrols each machine. From there you provision bare metal, build clusters, catalogue models, and serve them — without any of it leaving your network.

Note on scope. Earlier versions of this README described Aegis as an Envoy gateway with AI threat analysis. That is now one subsystem of several. The gateway still does everything it did; the product around it grew.

---

Quick start

mkdir aegis && cd aegis

curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml
mkdir envoy
curl -o envoy/envoy.yaml https://raw.githubusercontent.com/axieyangb/aegis/main/envoy/envoy.yaml

docker compose up -d

Open http://localhost:8765 — default login admin / changeme.

Set ADMIN_PASSWORD in docker-compose.yml before exposing this to anything.

Then enrol a machine — one line on the target, no SSH keys to distribute and no inbound ports to open:

curl -fsSL "http://<your-hub>:8765/install.sh?token=<join-token>" | sudo bash

The node dials out to the hub, receives an identity signed by your hub's own CA, and appears in the fleet. Bare metal with a BMC can instead be powered on and installed from the UI.

Requirements: the hub needs any Linux host with Docker (2 vCPU / 2 GB is plenty). Nodes need Linux with systemd, x86_64 or arm64. GPUs are detected and scheduled on automatically. Internet access is optional after the first pull.

---

What it does

Fleet	One-line enrolment, per-node mTLS identity, digest-verified agent upgrades with systemd auto-rollback, activity log
Networking	WireGuard overlay mesh, STUN NAT traversal, automatic LAN-direct routing with mesh fallback, embedded fleet DNS for hosts and containers
Gateway	Envoy with a full xDS control plane, SDS certificate management, automated TLS issuance, staged pending→apply config, rate limiting, one-click Expose
Bare metal	Redfish/BMC power control, UEFI HTTP Boot with no L2 adjacency required, serial console, libvirt/KVM provisioning with cloud-init
Kubernetes	Create, scale, upgrade, back up, restore and tear down clusters via a reconciler — k3s and kubeadm, with air-gapped installs validated live
Models & data	Catalogue models and datasets with versions, digests and lineage; pull from HuggingFace once and stage to nodes over the LAN; quotas per owner
Your storage	Keep artifact bytes on your own NAS mount or cloud bucket, switched at runtime from the UI. Reference-only artifacts catalogue what you already have without copying it
Workloads	GPU-aware scheduling, managed volumes with a file browser, notebooks, serving, promote-a-result-into-the-catalogue
AI operations	Owl, an assistant that acts through risk-classified tools with prompt-injection defences — it has deployed and configured Prometheus end to end, unattended
Protection	AI threat analysis over gateway access logs, automatic blocking, patrol sweeps, notifications

---

What makes it different

Most of the above has a good commercial equivalent. These do not:

• Air-gap is the default, not an enterprise tier. A 5-node HA Kubernetes cluster installed with no internet access at all, validated live. It falls out of the architecture: the hub reaches the internet once, every node pulls from the hub.
• An AI operator that operates. Owl changes infrastructure through scoped, risk-classified tools — not a chat box that summarises a dashboard.
• Bare metal to running model in one control plane. The seams between MAAS, Rancher and Harbor are where an ops team currently lives.
• Your weights never touch our disk. We catalogue; your storage holds. A 57 GB repository can be registered in seconds having downloaded nothing.
• One transfer, then LAN. A node with no internet access still gets a 57.9 GB model.

---

What it does not do yet

Published deliberately, because finding this out later is worse:

Gap	Where it stands
Multi-user / RBAC	Single operator account. Ownership already threads through the data model; the identity layer on top is the next major workstream.
Control-plane HA	One hub, one database. Workloads survive a hub outage; management does not.
Managed training runs	The GPU scheduler, artifact capture and volumes all exist, but training is not yet modelled as a workload — a run is still started by hand.
Scale	Validated at nine nodes. We quote that number rather than implying a larger one.

---

Architecture

Aegis runs as two containers — the hub (control plane, API, UI) and Envoy (data plane, driven entirely over xDS). Agents on each node dial out to the hub over a persistent connection, so no node needs an inbound port and nothing needs an SSH key distributed to it.

See deployment architectures for direct exposure, VPS relay and Cloudflare Tunnel topologies, and sequence diagrams for the request paths.

---

Configuration

Everything is environment variables in docker-compose.yml. See configs/ for annotated examples and envoy-config.md for the gateway bootstrap.

---

Docs & tutorials

• Getting started
• AI setup — connecting Owl to a model provider
• Notifications
• Deployment architectures

Tutorial series: exposing a service with Aegis

1. Local HTTPS with whoami
2. AI setup
3. Understanding the dashboard
4. AI-driven protection

Videos

Self-Host a Service with HTTPS Install Aegis, port-forward your router, set up No-IP DDNS, and issue a Let's Encrypt cert — ending with a live public HTTPS service.

AI Configures HTTPS Gateway and TLS Certificates One prompt to Owl AI sets up the cluster, issues a certificate, and wires the filter chain — no YAML, no restarts.

---

License

Distributed as a compiled binary. Source code is proprietary. See LICENSE.

Community tier is free forever. Pro unlocks unlimited notification channels, longer log retention, and unlimited AI patrol sweeps.

---

About

Built and run on a real fleet — nine nodes spanning LAN, cloud and overlay-only, managed through this platform daily. Questions are welcome at aegis.jerxie.com, where an assistant answers from this documentation, including the parts about what Aegis cannot do yet.