Skip to content

Getting Started

This guide walks you through installing AgentOps locally with Docker Compose, logging into the dashboard, running a first workflow, and using core security features.

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/AgentOps.git
cd AgentOps

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 6380→6379 Redis 7 cache and event bus
opa 8181 Open Policy Agent
app 8001 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:8001/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:8001/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:8001/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:8001/api/v1/health

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

Next Steps