/

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:

Tier Who Operates It Best For
Managed AegisWire SMEs and mid-market organisations wanting zero infrastructure management
Self-Hosted Your team Engineering teams, labs, and organisations wanting full control
Enterprise Contract-dependent Banks, healthcare, multi-region organisations needing dedicated infrastructure
Hardware Your team (on appliance) Branch offices and data-sovereignty requirements

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 the private registry. Self-hosted customers receive image pull credentials via the customer portal at app.aegiswire.com:

# Authenticate with the AegisWire container registry (credentials from your portal)
docker login registry.aegiswire.com

docker pull registry.aegiswire.com/controlplane:latest
docker pull registry.aegiswire.com/gateway:latest

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.aegiswire.com/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.aegiswire.com/gateway:latest
    environment:
      AW_CP_ENDPOINT: "http://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 AWT 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