Getting Started

Requirements

Docker and Docker Compose
Port 8765 accessible on your local network (dashboard)
Ports 80 and 443 open if you want Envoy to handle public internet traffic

1. Download the starter files

Create a new directory for Aegis and download the required configuration files:

mkdir aegis && cd aegis

# Download docker-compose config
curl -O https://raw.githubusercontent.com/axieyangb/aegis/main/docker-compose.yml

# Download Envoy bootstrap configuration
mkdir envoy
curl -o envoy/envoy.yaml https://raw.githubusercontent.com/axieyangb/aegis/main/envoy/envoy.yaml

2. Set your admin password

Edit docker-compose.yml and change ADMIN_PASSWORD=changeme to something secure.

3. Start the gateway

docker compose up -d

Aegis dashboard: http://localhost:8765
Default login: admin / changeme (or the password you set in ADMIN_PASSWORD)

On first boot, Aegis automatically seeds the database with a working baseline configuration — an HTTP listener (port 10080) that redirects to HTTPS and handles ACME challenges, and an HTTPS listener (port 10443) ready for SNI-based TLS routing. No file import required.

4. Add your first service

Configure a backend cluster:

Go to Gateway → Clusters and add a cluster pointing to your upstream service (hostname/IP + port).

Configure TLS:

For an internet-facing domain: go to Certificates → Signing Providers, add an ACME provider (Let's Encrypt), then issue a cert for your domain. See TLS with ACME below.
For an internal or lab service: use the built-in Local CA — no domain, no open ports required. See Local CA below.

Wire your domain to the listener:

Go to Gateway → Listeners → https_listener and add a filter chain for your domain: set the SNI match, point it to your cluster, and attach the TLS certificate secret.

You should see "xDS synced" in green on the Gateway page, confirming Envoy has loaded the configuration.

TLS with ACME (Let's Encrypt)

For domains that are publicly reachable:

Go to Certificates → Signing Providers → Add Provider
Choose ACME, select Let's Encrypt, set your email, and pick a challenge type:
- HTTP-01 — easiest; requires port 80 open and domain pointing here
- DNS-01 — works behind NAT; requires Cloudflare / Route 53 / GoDaddy API access
Go to Certificates → Managed Certs → Issue Certificate, choose your provider and domain
Aegis solves the challenge and pushes the cert to Envoy SDS automatically
Auto-renewal runs 30 days before expiry — no action needed

Local CA for internal use

For internal services, home lab, or dev environments where you don't have a public domain:

Go to Certificates → Signing Providers → Add Provider, choose Local CA
Go to Certificates → Managed Certs → Issue Certificate, select the Local CA provider and enter any hostname (e.g. homelab.local)
The cert is issued instantly and pushed to Envoy — no domain validation, no open ports
Download the Root CA certificate from the Certificates page and install it in your browser or OS trust store so the cert is trusted

By default Aegis auto-generates a 10-year ECDSA Root CA on first use. If you already have your own CA (corporate PKI, internal CA), you can import it instead: go to Certificates → Local CA → Import CA and upload your CA certificate and private key in PEM format. Aegis will use your CA to sign all subsequent leaf certificates.

All certs issued by the Local CA auto-renew via Aegis before expiry.

What's next

Try the Local CA tutorial — Tutorial: Local HTTPS with whoami walks through adding a service, issuing a cert, and accessing it over HTTPS from your browser — a good end-to-end test of your setup
IP Intelligence — enable AI classification in Settings → AI to automatically profile and classify every IP that hits your gateway
Notifications — connect Telegram, Slack, or a webhook in Settings → Integrations to get alerted on threats and anomalies
Owl AI — click the owl icon to chat with your gateway in plain language