Configuration

vega-core is configured through two mechanisms: environment variables (for production containers) and explicit dataclass objects (for programmatic injection). All configuration ultimately flows through RuntimeConfig in src/runtime/config.py.

`RuntimeConfig`

@dataclass(frozen=True)
class RuntimeConfig:
    policy: RunPolicy
    artifacts: ArtifactStoreConfig
    codex: CodexRuntimeConfig

    @classmethod
    def from_env(cls, env: Mapping[str, str] | None = None) -> RuntimeConfig: ...

from_env() reads the environment variables described below and builds a RuntimeConfig. Pass env=dict(os.environ) explicitly or omit it to use os.environ.

`RunPolicy`

Controls which stages run and how:

@dataclass(frozen=True)
class RunPolicy:
    enabled_stages: tuple[StageName, ...] = ()
    # empty = all stages; non-empty = only listed stages run
    agent_provider: str | None = None
    model: str | None = None
    max_workers_per_runner: int = 1
    # parallel component audit threads
    max_fast_runners_per_scan: int = 1
    max_cost_cents: int | None = None
    stage_timeout_seconds: Mapping[StageName, int] = field(default_factory=dict)
    retry_count: int = 0
    verify_before_patch: bool = True
    metadata: Mapping[str, Any] = field(default_factory=dict)
    # metadata["plugin_id"], metadata["plugin"], metadata["target_os"] etc.

`ArtifactStoreConfig`

ArtifactStoreKind = Literal["local", "s3"]

@dataclass(frozen=True)
class ArtifactStoreConfig:
    kind: ArtifactStoreKind = "local"
    local_root: Path = Path(".vega-artifacts")
    s3_bucket: str | None = None
    s3_prefix: str = ""
    s3_region_name: str | None = None
    s3_endpoint_url: str | None = None
    # STS assume-role for scan-scoped S3 credentials
    s3_scan_role_arn: str | None = None
    s3_scan_policy_json: str | None = None
    s3_scan_session_duration_seconds: int = 3600
    s3_scan_external_id: str | None = None
    s3_scan_sts_region_name: str | None = None
    s3_scan_session_name: str | None = None

`CodexRuntimeConfig`

@dataclass(frozen=True)
class CodexRuntimeConfig:
    codex_bin: str = "codex"
    model_reasoning_effort: str | None = None
    cwd: Path | None = None
    env: Mapping[str, str] = field(default_factory=dict)
    collab: bool = True

Environment variable reference

Policy variables

Variable	`RunPolicy` field	Notes
`VEGA_ENABLED_STAGES`	`enabled_stages`	Comma-separated `StageName` values
`VEGA_AGENT_PROVIDER`	`agent_provider`	Agent provider name
`VEGA_MODEL`	`model`	Model identifier
`VEGA_MAX_WORKERS_PER_RUNNER`	`max_workers_per_runner`	Parallel audit workers
`VEGA_CORE_AUDIT_WORKERS_MAX`	`max_workers_per_runner`	Alias for the above
`VEGA_MAX_FAST_RUNNERS_PER_SCAN`	`max_fast_runners_per_scan`	Runner container count
`VEGA_MAX_COST_CENTS`	`max_cost_cents`	Budget limit in cents
`VEGA_STAGE_TIMEOUT_SECONDS`	`stage_timeout_seconds`	JSON map of stage name → seconds
`VEGA_RETRY_COUNT`	`retry_count`	Retry count for failed stages
`VEGA_VERIFY_BEFORE_PATCH`	`verify_before_patch`	`"true"` or `"false"`

Policy metadata variables

These go into RunPolicy.metadata:

Variable	Key in metadata
`VEGA_AGENT_TIMEOUT_SECONDS`	`"agent_timeout_seconds"`
`VEGA_DEFAULT_AGENT_TIMEOUT_SECONDS`	`"default_agent_timeout_seconds"`
`VEGA_CODEX_TIMEOUT_SECONDS`	`"codex_timeout_seconds"`
`VEGA_SCAN_DEPTH`	`"scan_depth"`
`VEGA_PLUGIN_ID`	`"plugin_id"`
`VEGA_TARGET_OS`	`"target_os"`

Artifact store variables

Variable	Effect
`VEGA_ARTIFACT_STORE`	`"local"` or `"s3"`
`VEGA_ARTIFACT_ROOT`	Local artifact directory
`VEGA_ARTIFACT_S3_BUCKET`	S3 bucket (also `VEGA_S3_ARTIFACT_BUCKET`)
`VEGA_ARTIFACT_S3_PREFIX`	S3 key prefix
`VEGA_ARTIFACT_S3_REGION`	S3 region (also falls back to `AWS_REGION`)
`VEGA_ARTIFACT_S3_ENDPOINT_URL`	Custom S3 endpoint
`VEGA_S3_SCAN_ROLE_ARN`	STS role for scan-scoped credentials
`VEGA_S3_SCAN_POLICY_JSON`	Inline session policy JSON
`VEGA_S3_SCAN_SESSION_DURATION_SECONDS`	Role session duration
`VEGA_S3_SCAN_EXTERNAL_ID`	External ID for role assumption
`VEGA_S3_STS_REGION`	STS region (also falls back to `AWS_REGION`)
`VEGA_S3_SCAN_SESSION_NAME`	STS session name

Codex / agent variables

Variable	Effect
`VEGA_CODEX_BIN`	Path to the `codex` binary
`VEGA_CODEX_CWD`	Working directory for codex subprocess
`VEGA_CODEX_REASONING_EFFORT`	`"low"`, `"medium"`, or `"high"`
`VEGA_CODEX_COLLAB`	`"true"` or `"false"` — collab mode flag
`OPENAI_API_KEY`	API key passed to Codex subprocess env
`OPENAI_BASE_URL`	Base URL (for vega-llm-proxy or custom endpoint)
`VEGA_CORE_CODEX_CONFIG_JSON`	Full Codex config override JSON
`VEGA_CODEX_MULTI_AGENT_ENABLED`	Enable multi-agent Codex mode

Runtime service construction

build_runtime_services(config, *, event_sink, cancellation_token) creates:

EventBus wired to the caller-supplied event_sink
LocalArtifactStore or S3ArtifactStore depending on config.artifacts.kind
CancellationManager wrapping the caller-supplied token
AgentRunner with a CodexAdapter built from config.codex
PluginResolver backed by production_plugin_registry() (includes LinuxPlugin, WebApplicationPlugin, DefaultPlugin in priority order)
SharedTriageService
Default RunPolicy

build_stage_orchestrator(config, ...) wraps all of the above in a StageOrchestrator.

Local development config (minimal)

export VEGA_ARTIFACT_STORE=local
export VEGA_ARTIFACT_ROOT=./.vega-artifacts   # default if unset
export VEGA_CODEX_BIN=codex
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=http://localhost:4000/v1  # if using llm-proxy

Production config (S3 + role assumption)

export VEGA_ARTIFACT_STORE=s3
export VEGA_ARTIFACT_S3_BUCKET=vega-artifacts-prod
export VEGA_ARTIFACT_S3_PREFIX=scans/
export VEGA_ARTIFACT_S3_REGION=us-east-1
export VEGA_S3_SCAN_ROLE_ARN=arn:aws:iam::123456789:role/vega-scan
export VEGA_MAX_WORKERS_PER_RUNNER=4
export VEGA_STAGE_TIMEOUT_SECONDS='{"audit": 1800, "verify": 600}'
export VEGA_CODEX_BIN=/usr/local/bin/codex
export VEGA_CODEX_REASONING_EFFORT=high
export OPENAI_BASE_URL=https://llm-proxy.internal/v1