Skip to content

Quickstart

Deploy Vex Raptor with Docker and run your first authorized scan.

Authorized testing only

Only run scans against systems you own or have explicit written permission to test. See Responsible use.

Prerequisites

  • Docker and Docker Compose
  • ~2 vCPU / 2 GB RAM minimum for a small deployment
  • A target you are authorized to test

1. Configure the environment

Copy the example environment file and set, at minimum, a SECRET_KEY:

cp .env.example .env
python -c "import secrets; print(secrets.token_hex(64))"   # paste into SECRET_KEY

Key variables (full list in Configuration):

Variable Required Purpose
SECRET_KEY Yes Signs JWT session tokens
ENVIRONMENT Prod dev for local lab only; prod for any Internet-facing deploy
VEX_LICENSE_KEY Prod License JWT from Vex — required to start in production
DATABASE_URL Prod PostgreSQL DSN (SQLite if empty)
REDIS_URL / REDIS_ENABLED Prod Queue, quota, shared scan state
VEX_LLM_PROVIDER + key For AI depth gemini / vertex / bedrock / mistral / ollama

Local lab vs production

ENVIRONMENT=dev is for localhost/lab targets only. For any deployment reachable from the Internet you must set ENVIRONMENT=prod, obtain a VEX_LICENSE_KEY from Vex, and prove domain ownership before scanning external targets. See Responsible use.

2. Start the stack

docker compose up -d
docker compose ps            # all services healthy

The stack runs the API, a background worker, PostgreSQL, and Redis. The web UI and API are served on the app port; check /health:

curl -s http://localhost:8000/health

3. Create the first admin

python scripts/create_admin.py --role admin

4. Log in and run a scan

  1. Open the console in your browser and log in (accounts are provisioned by your org admin — there is no public self-registration).
  2. Go to Pentest.
  3. Enter your authorized target URL.
  4. For external targets in production, complete domain verification first (DNS TXT or .well-known file — the console returns instructions on 403).

  5. Choose a depth:

    • Recon — infrastructure only, fast (< 3 min)
    • Full — adds active attacks and the bounded arsenal_lite phase
    • AI — adds the LLM analysis layer

  6. Start the scan and watch the phase timeline stream live.

See Scan depths for what each depth runs.

5. Read the report

When the scan completes, open the report. Findings are grouped by severity and labelled by confidence (what was proven vs. what needs review), and confirmed findings include a reproducible proof of concept. See Read a report.

Next steps