Configuration
All configuration lives in app/core/settings.py as a Pydantic Settings class. Every field can be overridden with an environment variable named VEGA_<FIELD_NAME_UPPERCASE>.
For example, the field scan_execution_mode becomes VEGA_SCAN_EXECUTION_MODE.
You can set environment variables in your shell, in a .env file, or in an ECS task definition. The backend will pick them up automatically on startup.
Application
| Variable | Default | Description |
|---|---|---|
VEGA_APP_NAME |
Vega |
FastAPI application title (shown in /docs) |
VEGA_SERVICE_ROLE |
api |
Logical role: api, worker, maintenance, or llm-proxy. Affects logging and startup behavior. |
VEGA_API_PREFIX |
/v1 |
URL prefix for all API routes |
VEGA_ENVIRONMENT |
dev |
Environment name. Affects log labels. |
Storage and persistence
| Variable | Default | Description |
|---|---|---|
VEGA_PERSISTENCE_BACKEND |
json |
json stores data in local files under data/. postgres uses a Postgres database — required for production. |
VEGA_DATABASE_URL |
(none) | Postgres connection string, e.g. postgresql://user:pass@host:5432/vega. Also accepts DATABASE_URL. |
VEGA_FILE_STORAGE_BACKEND |
local |
local stores files under data/. s3 stores them in S3 buckets — required for production. |
VEGA_S3_SOURCE_BUCKET |
(none) | S3 bucket for source snapshots (code archives). |
VEGA_S3_ARTIFACTS_BUCKET |
(none) | S3 bucket for scan artifacts (reports, debug bundles). |
VEGA_S3_EXPORTS_BUCKET |
(none) | S3 bucket for user-downloadable exports. |
Scan execution
This is one of the most important groups of settings. It controls whether scans run inside the API process, in a separate worker, or via SQS + ECS.
| Variable | Default | Description |
|---|---|---|
VEGA_SCAN_EXECUTION_MODE |
thread |
How the API dispatches scans. See below. |
VEGA_SCAN_WORKER_EXECUTION_MODE |
local |
How the worker runs scans. local runs in the worker process. ecs launches an ECS task. |
VEGA_SCAN_QUEUE_URL |
(none) | SQS queue URL. Required when VEGA_SCAN_EXECUTION_MODE=sqs. |
VEGA_SCAN_RUNNING_STALE_SECONDS |
21600 (6 hours) |
A running scan older than this threshold is considered stale and eligible for recovery. |
Execution mode values:
VEGA_SCAN_EXECUTION_MODE |
What happens when a scan is created |
|---|---|
thread |
The API process starts the scan immediately in a background thread. Simple for local dev. |
external |
The API records the scan as queued. A separately running worker must pick it up. |
sqs |
The API sends a message to SQS. A worker consuming SQS messages picks it up. Used in production. |
Never use thread in production
thread mode ties scan execution to the API process. Long-running scans will hold up API threads and the process can crash mid-scan. Use sqs in production.
v16 and Codex
The v16 scan engine uses Codex (an AI CLI tool) to do the actual code analysis. These settings control how v16 finds and runs Codex.
| Variable | Default | Description |
|---|---|---|
VEGA_V16_ROOT |
v16/ |
Path to the v16 submodule directory |
VEGA_V16_RUNTIME_ROOT |
(data dir) | Where v16 writes its working files during a scan |
VEGA_V16_CODEX_BIN |
scripts/codex-in-target-container.sh |
Command used to invoke Codex. The default runs Codex in an isolated Docker container. Override with a plain codex binary for debugging. |
VEGA_V16_CODEX_DOCKER_IMAGE |
vega-codex-runner:latest |
Docker image used for Codex isolation |
VEGA_V16_MODEL |
gpt-5.4 |
AI model name passed to Codex |
LLM proxy
The LLM proxy sits between scan runners and the AI provider. Runners call the proxy; the proxy calls the provider. This keeps provider credentials out of runner containers.
| Variable | Default | Description |
|---|---|---|
VEGA_LLM_PROXY_BASE_URL |
(none) | Internal URL of the proxy service. Set this in runner containers so Codex routes through the proxy. |
VEGA_LLM_PROXY_AUTH_SECRET |
(none) | Secret used to sign and verify per-scan proxy tokens |
VEGA_LLM_PROVIDER_BASE_URL |
(none) | The AI provider's API base URL (e.g., OpenAI-compatible endpoint) |
VEGA_LLM_PROVIDER_API_KEY |
(none) | Provider API key. Owned by the proxy service, not the runners. |
VEGA_LLM_PROXY_MAX_REQUESTS_PER_SCAN |
0 (disabled) |
Hard cap on AI requests per scan. 0 means no limit. |
VEGA_LLM_PROXY_MAX_TOKENS_PER_SCAN |
0 (disabled) |
Hard cap on tokens per scan. 0 means no limit. |
VEGA_LLM_PROXY_MAX_COST_USD_PER_SCAN |
0 (disabled) |
Hard cap on estimated cost per scan in USD. 0 means no limit. |
Authentication
| Variable | Default | Description |
|---|---|---|
VEGA_AUTH_PROVIDER |
custom |
custom uses simple debug credentials. cognito uses AWS Cognito JWTs — required for production. |
VEGA_AUTH_SECRET |
(generated) | Signing secret for local auth tokens. |
VEGA_COGNITO_REGION |
(none) | AWS region of the Cognito user pool, e.g. us-west-1 |
VEGA_COGNITO_USER_POOL_ID |
(none) | Cognito user pool ID |
VEGA_COGNITO_APP_CLIENT_ID |
(none) | Cognito app client ID |
Resource limits
| Variable | Default | Description |
|---|---|---|
VEGA_MAX_ACTIVE_SCANS_PER_USER |
4 |
Maximum concurrent scans for a single user |
VEGA_MAX_SOURCE_BYTES |
2147483648 (2 GB) |
Maximum allowed source archive size |
VEGA_MAX_ARCHIVE_ENTRIES |
50000 |
Maximum number of files in an uploaded archive |
VEGA_MAX_ARCHIVE_UNCOMPRESSED_BYTES |
5368709120 (5 GB) |
Maximum total uncompressed size of an archive |
VEGA_WORKER_HEARTBEAT_TTL_SECONDS |
120 |
A worker that hasn't sent a heartbeat in this long is considered stale |
Configuration examples
No extra configuration needed. Start the backend and it uses JSON files and thread-mode scans:
uvicorn app.main:app --reload --reload-dir app
# Terminal 1 — API
VEGA_SCAN_EXECUTION_MODE=external uvicorn app.main:app --reload --reload-dir app
# Terminal 2 — worker
python scripts/run-scan-worker.py
VEGA_ENVIRONMENT=prod \
VEGA_PERSISTENCE_BACKEND=postgres \
VEGA_DATABASE_URL=postgresql://user:pass@host:5432/vega \
VEGA_FILE_STORAGE_BACKEND=s3 \
VEGA_S3_SOURCE_BUCKET=vega-prod-source-abc123 \
VEGA_S3_ARTIFACTS_BUCKET=vega-prod-artifacts-abc123 \
VEGA_SCAN_EXECUTION_MODE=sqs \
VEGA_SCAN_QUEUE_URL=https://sqs.us-west-1.amazonaws.com/123/vega-prod-scans \
VEGA_AUTH_PROVIDER=cognito \
VEGA_COGNITO_REGION=us-west-1 \
VEGA_COGNITO_USER_POOL_ID=us-west-1_xxxxx \
VEGA_COGNITO_APP_CLIENT_ID=xxxxx \
uvicorn app.main:app
In AWS, use Secrets Manager
In production, sensitive values (database URL, API keys, Cognito IDs) come from AWS Secrets Manager and are injected into ECS task definitions. Never commit real credentials to version control.