Skip to content

Getting Started

This guide walks you through installing AegisAI locally with Docker Compose, logging into the dashboard, and performing your first security operations.

Prerequisites

Requirement Version Notes
Docker 24+ With Docker Compose v2
Git 2.x To clone the repository
curl any For API smoke tests (optional)

Optional: local development

For backend-only development without Docker, you also need Python 3.11+, Poetry, and a local PostgreSQL instance. See the Developer Guide.

Clone the Repository

git clone https://github.com/valera7623/AegisAI.git
cd aegisai

Configure Environment

Copy the example environment file and review key settings:

cp .env.example .env

Important variables in .env and docker-compose.yml:

Variable Default Purpose
DATABASE_URL postgresql+asyncpg://aegisai:aegisai_pass@postgres:5432/aegisai PostgreSQL connection
REDIS_URL redis://redis:6379/0 Redis for pub/sub and caching
SECRET_KEY dev-secret-key-change-in-production JWT signing key
ADMIN_API_KEY admin-key Tenant provisioning (X-Admin-Key)
OPA_ENABLED true Enable OPA policy engine
OPA_URL http://opa:8181 OPA server address
SUPER_ADMIN_EMAIL admin@aegisai.com Initial super-admin account
SUPER_ADMIN_PASSWORD admin123 Initial super-admin password
SUPER_ADMIN_SYNC_PASSWORD true Sync super-admin password from env on startup
WEBHOOK_SECRET webhook-secret-key HMAC signing for webhooks
KEYCLOAK_ENABLED false Enable Keycloak SSO (see SSO)
SIEM_ENABLED false Enable SIEM event export (see SIEM)
ENABLE_GUARD true Prompt Guard middleware + API (see Prompt Guard)
GUARD_MODEL_PATH ./models/guard/guard_model.pkl Optional trained ML artifact

Start the Platform

docker compose up --build

Docker Compose starts five services:

Service Port Description
postgres 5432 PostgreSQL 15 database
redis 6379 Redis 7 cache and event bus
opa 8181 Open Policy Agent
app 8000 FastAPI backend
frontend 5173 Vite dashboard SPA

On first boot, the app container automatically:

  1. Runs Alembic migrations (alembic upgrade head)
  2. Creates the super-admin user (scripts/init_super_admin.py)
  3. Loads Rego policy templates into OPA
  4. Starts the Uvicorn API server

Verify services

Wait until all containers report healthy, then open http://localhost:5173.

Log In to the Dashboard

Email and password

  1. Navigate to http://localhost:5173
  2. Enter the super-admin credentials:
  3. Email: admin@aegisai.com
  4. Password: admin123
  5. Click Sign In

SSO (optional)

When an Identity Provider is configured (KEYCLOAK_ENABLED, OKTA_ENABLED, etc.), the login page shows Sign in with … buttons. See SSO Configuration for setup.

On successful login, the API returns:

  • A JWT access token (stored in browser session)
  • A session API key (used as X-API-Key for tenant-scoped requests)

The dashboard stores both credentials automatically.

Create a Tenant (Optional)

Super-admins and provisioning scripts can create tenants via the admin API key:

curl -X POST http://localhost:8000/api/v1/tenants \
  -H "X-Admin-Key: admin-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo-tenant"}'

The response includes a tenant api_key. Save it — it is shown only once.

Configure API Key in Settings

If you received a tenant API key (from tenant creation or seed data):

  1. Open Settings in the sidebar
  2. Paste the API key into the API Key field
  3. Click Save

The dashboard uses this key for all /api/v1/* requests via the X-API-Key header.

Seed Demo Data (Optional)

Two scripts are available:

Legacy seed (2 tenants, agents, policies):

docker compose exec app poetry run python scripts/seed_data.py --reset

Extended demo data (3 tenants, 10k audit logs, direct DB seeding):

./scripts/run_demo_data.sh --reset
Tenant Demo API Key (seed_data)
Acme Corp aegis_acme_demo_seed_key_001
MedTech Inc aegis_medtech_demo_seed_key_002

First Steps

After logging in, complete these tasks to familiarize yourself with the platform:

1. Review the Dashboard

Open Dashboard to see KPI cards (agents, policies, anomalies, pending HITL) and the 7-day activity chart.

2. Register an Agent

Use the Python SDK or API:

curl -X POST http://localhost:8000/api/v1/agents/register \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "type": "llm",
    "capabilities": ["observe", "track"]
  }'

3. Create a Policy

Navigate to Policies → Create Policy and select a template (e.g., GDPR Compliance). Customize rules and activate the policy.

4. Run a Policy Check

curl -X POST http://localhost:8000/api/v1/policies/check \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent-uuid>",
    "action": "read_data",
    "resource": "customer_pii",
    "context": {"consent": true, "lawful_basis": "consent"}
  }'

5. Explore Audit Logs

Open Audit to view logged actions. Use filters and export to CSV or JSON.

Health Checks

Verify the platform is running:

# Liveness
curl http://localhost:8000/api/v1/health

# Readiness (checks DB, Redis, OPA)
curl http://localhost:8000/api/v1/health/ready

Next Steps