Configuration
All configuration is managed by RuntimeSettings in app/composition/settings/. Settings are loaded from environment variables (with a VEGA_ prefix), with profile-specific defaults applied based on VEGA_ENVIRONMENT.
Profiles (local, test, staging, production) provide sensible defaults so most settings don't need to be set explicitly in development. In production, sensitive values are pulled from AWS Secrets Manager at startup.
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.
Runtime
| Variable | Default | Description |
|---|---|---|
VEGA_SERVICE_ROLE |
api |
Process role: api, scan-worker, scan-runner, repository-ingest-worker, repository-ingest-runner, llm-proxy, maintenance. Affects which adapters are wired at startup. |
VEGA_API_PREFIX |
/api |
URL prefix for all API routes. The /v1 prefix is also accepted as a compatibility alias. |
VEGA_ENVIRONMENT |
local |
Environment profile: local, test, staging, or production. Controls profile defaults. |
VEGA_CORS_ALLOWED_ORIGINS |
["http://localhost:5173"] |
CORS origins allowed by the API. |
Storage and persistence
| Variable | Default | Description |
|---|---|---|
VEGA_PERSISTENCE_BACKEND |
json |
json stores all records as JSON files under data/. postgres uses a Postgres database with JSONB storage — required for production. |
VEGA_DATABASE_URL |
(none) | Postgres connection string, e.g. postgresql://user:pass@host:5432/vega. Also accepts DATABASE_URL without the prefix. |
VEGA_DATA_DIR |
./data |
Local directory for JSON files and local snapshots/artifacts. |
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
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 = in-process via LocalVegaCoreService. ecs = launches an ECS RunTask. |
VEGA_SCAN_QUEUE_URL |
(none) | SQS queue URL. Required when VEGA_SCAN_EXECUTION_MODE=sqs. |
VEGA_SCAN_RUNNING_STALE_SECONDS |
21600 (6 hours) |
Scans running longer than this are treated as stale and eligible for recovery. |
Execution mode values:
VEGA_SCAN_EXECUTION_MODE |
What happens when a scan is created |
|---|---|
thread |
The API runs ExecuteScanUseCase 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 the SQS scan queue. A worker consuming SQS picks it up. Used in production. |
Never use thread in production
Thread mode ties scan execution to the API process. Long scans hold API threads and the process can crash mid-scan. Use sqs in production.
Scan capacity config
ScanCapacityPolicy reads from VEGA_SCAN_CAPACITY_CONFIG_JSON (a JSON object):
| Field | Default | Description |
|---|---|---|
max_workers_per_runner |
4 |
Maximum audit workers (components) per ECS runner task |
max_fast_runners_per_scan |
1 |
Maximum parallel fast-mode runner tasks per scan |
max_verification_runners_per_scan |
0 |
Maximum parallel verification runner tasks per scan. 0 disables verification. |
# Enable finding verification with up to 2 concurrent verify tasks per scan
VEGA_SCAN_CAPACITY_CONFIG_JSON='{"max_verification_runners_per_scan": 2}'
Repository ingest execution
Controls how repository ingest jobs are dispatched.
| Variable | Default | Description |
|---|---|---|
VEGA_REPO_INGEST_EXECUTION_MODE |
local |
local = in-process ingest. sqs = enqueue to SQS. |
VEGA_REPO_INGEST_QUEUE_URL |
(none) | SQS queue URL for ingest jobs. Required when mode is sqs. |
VEGA_REPO_INGEST_WORKER_EXECUTION_MODE |
local |
local = ingest runs in the worker process. ecs = launches an ECS RunTask. |
VEGA_REPO_INGEST_RUNNING_STALE_SECONDS |
7200 (2 hours) |
Ingest jobs running longer than this are treated as stale. |
ECS runner configuration
Settings for the ECS task definitions used by scan and ingest runners.
| Variable | Description |
|---|---|
VEGA_ECS_CLUSTER |
ECS cluster ARN for launching runner tasks |
VEGA_ECS_SCAN_RUNNER_TASK_DEFINITION |
Task definition ARN for vega-scan-runner |
VEGA_ECS_INGEST_RUNNER_TASK_DEFINITION |
Task definition ARN for vega-repo-ingest-runner |
VEGA_ECS_RUNNER_SUBNETS |
Comma-separated subnet IDs for runner tasks (private subnets) |
VEGA_ECS_RUNNER_SECURITY_GROUPS |
Comma-separated security group IDs for runner tasks |
vega-core and Codex
| Variable | Default | Description |
|---|---|---|
VEGA_CORE_ROOT |
vega-core/ |
Path to the vega-core submodule directory |
VEGA_CORE_RUNTIME_ROOT |
(data dir) | Where vega-core writes its working files during a scan |
VEGA_CORE_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_CORE_CODEX_DOCKER_IMAGE |
vega-codex-runner:latest |
Docker image used for Codex isolation (local mode only) |
VEGA_CORE_MODEL |
gpt-5.4 |
AI model name passed to Codex |
VEGA_CORE_AUDIT_WORKERS_MAX |
4 |
Thread pool size for parallel component auditing in vega-core |
LLM proxy
| Variable | Default | Description |
|---|---|---|
VEGA_LLM_PROXY_BASE_URL |
(none) | Internal URL of the LLM proxy service. Set 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 (OpenAI-compatible) |
VEGA_LLM_PROVIDER_API_KEY |
(none) | Provider API key. Held by the proxy service, not runners. |
VEGA_LLM_PROXY_MAX_REQUESTS_PER_SCAN |
0 (disabled) |
Hard cap on AI requests per scan |
VEGA_LLM_PROXY_MAX_TOKENS_PER_SCAN |
0 (disabled) |
Hard cap on tokens per scan |
VEGA_LLM_PROXY_MAX_COST_USD_PER_SCAN |
0 (disabled) |
Hard cap on estimated cost per scan in USD |
Authentication
| Variable | Default | Description |
|---|---|---|
VEGA_AUTH_PROVIDER |
custom |
custom uses simple local debug credentials. cognito uses AWS Cognito JWTs — required for production. |
VEGA_COGNITO_REGION |
(none) | AWS region of the Cognito user pool |
VEGA_COGNITO_USER_POOL_ID |
(none) | Cognito user pool ID |
VEGA_COGNITO_APP_CLIENT_ID |
(none) | Cognito app client ID |
Integrations
| Variable | Description |
|---|---|
VEGA_GITHUB_APP_ID |
GitHub App ID for repository access |
VEGA_GITHUB_APP_PRIVATE_KEY |
GitHub App private key (PEM, base64-encoded) |
VEGA_STRIPE_SECRET_KEY |
Stripe secret key for payment processing |
VEGA_STRIPE_WEBHOOK_SECRET |
Stripe webhook signing secret |
VEGA_SUB2API_BASE_URL |
Sub2API service URL for billing and LLM key management |
VEGA_SUB2API_API_KEY |
Sub2API API key |
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 |
AWS Secrets Manager
In production, RuntimeSettings can pull sensitive configuration from AWS Secrets Manager. Set VEGA_SECRETS_ARN to the ARN of a Secrets Manager secret that contains a JSON object with any of the above settings. Values from Secrets Manager override environment variable values.
VEGA_SECRETS_ARN=arn:aws:secretsmanager:us-west-1:123456789:secret:vega-prod-config-xxxx
This keeps sensitive values (database URL, API keys, Cognito IDs) out of ECS task definitions and CloudFormation templates.
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 (scan execution deferred to worker)
VEGA_SCAN_EXECUTION_MODE=external uvicorn app.main:app --reload --reload-dir app
# Terminal 2 — scan worker
python scripts/run-scan-worker.py
# Terminal 3 — ingest worker (if testing ingest separately)
python scripts/run-repo-ingest-worker.py
VEGA_ENVIRONMENT=production \
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_REPO_INGEST_EXECUTION_MODE=sqs \
VEGA_REPO_INGEST_QUEUE_URL=https://sqs.us-west-1.amazonaws.com/123/vega-prod-ingest \
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) should come from AWS Secrets Manager via VEGA_SECRETS_ARN. Never commit real credentials to version control.