Local vs AWS Runtime

Vega is designed to run in two very different ways: a simple single-machine local setup for development, and a distributed AWS setup for production. The same codebase supports both through environment variables.

Side-by-side comparison

Concern	Local development	AWS production
Metadata storage	JSON files under `data/`	Postgres (RDS/Aurora)
File storage	Local directories under `data/`	S3 buckets
Scan dispatch	`thread` (in-process) or `external`	`sqs` (SQS message queue)
Scan execution	API or worker process	Isolated ECS Fargate runner task
Authentication	Built-in debug credentials	AWS Cognito user pool + JWT validation
Logs	stdout / local files	CloudWatch log groups
Secrets	Environment variables	AWS Secrets Manager
Frontend serving	Vite dev server (port 5173)	S3 + CloudFront CDN
API serving	`uvicorn` directly (port 8000)	ECS Fargate behind an ALB
Codex container	Local Docker	Included in ECS runner task image

Why the difference matters

For developers: Local mode is fast to start and easy to reset. You don't need AWS credentials, a database, or any cloud services. JSON files are easy to inspect. Scans run immediately in the same process.

For production: AWS mode is durable, scalable, and isolated. Scan failures don't crash the API. Provider credentials are kept in the LLM proxy, not in every container. Source code and findings survive process restarts. Each scan runs in its own isolated task.

The gap between local and AWS is intentional — local mode optimizes for developer speed, AWS mode optimizes for reliability.

Key configuration differences

LocalAWS

# Minimal local setup — these are the defaults, no env vars needed
VEGA_PERSISTENCE_BACKEND=json
VEGA_FILE_STORAGE_BACKEND=local
VEGA_SCAN_EXECUTION_MODE=thread
VEGA_AUTH_PROVIDER=custom

VEGA_PERSISTENCE_BACKEND=postgres
VEGA_DATABASE_URL=postgresql://...
VEGA_FILE_STORAGE_BACKEND=s3
VEGA_S3_SOURCE_BUCKET=vega-prod-source-...
VEGA_S3_ARTIFACTS_BUCKET=vega-prod-artifacts-...
VEGA_SCAN_EXECUTION_MODE=sqs
VEGA_SCAN_QUEUE_URL=https://sqs.us-west-1.amazonaws.com/...
VEGA_SCAN_WORKER_EXECUTION_MODE=ecs
VEGA_AUTH_PROVIDER=cognito
VEGA_COGNITO_REGION=us-west-1
VEGA_COGNITO_USER_POOL_ID=...
VEGA_COGNITO_APP_CLIENT_ID=...

Transitioning from local to AWS

If you're running locally and want to test a more production-like setup before deploying to AWS:

Start a local Postgres database (e.g., with Docker: docker run -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:15)
Set VEGA_PERSISTENCE_BACKEND=postgres and VEGA_DATABASE_URL=postgresql://postgres:test@localhost:5432/vega
Run migrations: python scripts/run-db-migrations.py
Set VEGA_SCAN_EXECUTION_MODE=external and start the worker separately

This gets you the Postgres + separate worker experience without needing AWS.