Quickstart

This guide walks you through deploying a working AegisWire VPN environment. By the end, you will have a running control plane, a configured gateway pool, and a client device enrolled and tunnelling traffic.

Step 1: Choose Your Deployment Model

AegisWire supports several deployment tiers. Choose the one that matches your organisation:

For this quickstart, we will cover the Self-Hosted deployment using Docker Compose.

Step 2: Prepare the Environment

Ensure you have:

• Docker 24.0+ and Docker Compose v2
• PostgreSQL 15+ (or use the bundled PostgreSQL container)
• A domain name pointing to your server

Pull the AegisWire container images from AWS ECR. Self-hosted customers get temporary pull credentials from the Downloads page in the customer portal at app.aegiswire.com/portal/downloads:

1. Log in to the portal and go to Downloads
2. Click Generate Credentials to get a 12-hour ECR access token
3. Run the commands shown on the page:

# Set AWS credentials (from the Downloads page)
export AWS_ACCESS_KEY_ID=<from portal>
export AWS_SECRET_ACCESS_KEY=<from portal>
export AWS_SESSION_TOKEN=<from portal>

# Docker login (command shown on Downloads page)
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <REGISTRY>

# Pull images
docker pull <REGISTRY>/aegiswire/controlplane:latest
docker pull <REGISTRY>/aegiswire/gateway:latest

The <REGISTRY> URL and exact commands are provided by the portal — do not construct them manually.

Step 3: Configure the Control Plane

Create a docker-compose.yml for your deployment:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: aegiswire
      POSTGRES_USER: aegiswire
      POSTGRES_PASSWORD: "${AW_DB_PASSWORD}"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U aegiswire"]
      interval: 5s
      timeout: 3s
      retries: 5

  controlplane:
    image: <REGISTRY>/controlplane:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      AW_DB_DSN: "postgres://aegiswire:${AW_DB_PASSWORD}@postgres:5432/aegiswire?sslmode=disable"
      AW_LISTEN_ADDR: ":8443"
      AW_ADMIN_LISTEN_ADDR: ":8080"
      AW_DOMAIN: "${AW_DOMAIN}"
    ports:
      - "8443:8443"
      - "8080:8080"
    volumes:
      - cpdata:/var/lib/aegiswire

  gateway:
    image: <REGISTRY>/gateway:latest
    environment:
      # HTTPS is required for the gateway -> control-plane channel. The
      # control plane terminates TLS itself here (AW_LISTEN_ADDR :8443
      # serves HTTPS with your certificate); if you instead terminate TLS
      # at a reverse proxy / load balancer, point this at that HTTPS
      # endpoint. Plaintext http:// endpoints are rejected by AegisWire's
      # enrollment/endpoint validation and must never appear in a
      # production deployment.
      AW_CP_ENDPOINT: "https://controlplane:8443"
      AW_GATEWAY_LISTEN: ":51820/udp"
    ports:
      - "51820:51820/udp"
    cap_add:
      - NET_ADMIN

volumes:
  pgdata:
  cpdata:

Create a .env file with your configuration:

AW_DB_PASSWORD=your-secure-database-password
AW_DOMAIN=vpn.yourdomain.com

Step 4: Start the Services

docker compose up -d

Verify all services are healthy:

docker compose ps

You should see the postgres, controlplane, and gateway services running.

Step 5: Access the Admin Interface

Open your browser and navigate to the control plane admin interface:

https://vpn.yourdomain.com:8080/admin/

On first launch, the control plane will prompt you to create an initial administrator account. This uses the built-in user management system — no external identity provider is needed.

Create Your First Admin User

1. Set an admin username and strong password
2. Configure MFA using the TOTP QR code (recommended)
3. Log in with your new credentials

Step 6: Create a Gateway Pool

From the admin interface:

1. Navigate to Gateway Pools
2. Click Create Pool
3. Enter a name (e.g., "Primary Gateway")
4. Select the region and configure the endpoint address
5. The gateway container will automatically register with the control plane

Step 7: Generate an Enrollment Token

To enroll a client device:

1. Navigate to Enrollment Tokens
2. Click Generate Token
3. Select the target user (or create a new user)
4. Choose token type: Single Use or Time Limited
5. Copy the enrollment token or QR code

Step 8: Enroll a Client Device

Coming Soon — Native client applications for macOS, Windows, iOS, and Android are currently in development. Once available, enrollment will work as follows:

1. Open the AegisWire client application on the target device
2. Enter the control plane URL: https://vpn.yourdomain.com:8443
3. Paste or scan the enrollment token
4. The client performs the enrollment handshake with the control plane
5. On success, the device receives its credentials and the latest policy

The enrollment API endpoint (/v1/enroll) is already implemented in the Go control plane and ready for client integration.

Step 9: Connect

Coming Soon — VPN tunnel connectivity requires a native client application. This step will be available once client development is complete.

After enrollment, the client will:

1. Resolve the gateway endpoint from the control plane policy
2. Initiate the AegisWire secure handshake with hybrid post-quantum key exchange
3. Establish the encrypted tunnel
4. Route traffic according to the configured policy (full tunnel or split tunnel)

What You Can Do Now

With the control plane and gateway deployed, you can:

• Create users and groups via the admin interface
• Configure policies (tunnel mode, DNS, access rules)
• Generate enrollment tokens ready for when client apps are available
• Set up gateway pools and configure gateway endpoints
• Configure identity providers for SSO federation

Verify the control plane is healthy:

curl https://vpn.yourdomain.com:8443/healthz

Next Steps

• Configure policies for your organisation
• Set up user management and roles
• Deploy additional gateways for redundancy
• View client development status for platform availability