Skip to content

Local Scripts

Local scripts are useful during development when you want to run the scan worker, execute a specific scan, run migrations, or test Codex container behavior without deploying to AWS.

Scan worker

python scripts/run-scan-worker.py

Starts a long-running worker process. Required when VEGA_SCAN_EXECUTION_MODE=external (the API queues scans but doesn't run them). The worker:

  1. Sends heartbeats to track liveness
  2. Recovers stale scans (stuck running scans where the runner crashed)
  3. Polls for new scans from the queue (or scans in queued state for external mode)
  4. Claims each scan and runs it locally or launches an ECS task

When to use: any time you want to test the scan pipeline in a realistic multi-process setup.

Scan runner (run one scan manually)

python scripts/run-scan-runner.py <scan_id>

Runs a single already-queued scan directly, mimicking exactly what the ECS runner task does. This is the most direct way to debug scan execution without spinning up AWS infrastructure.

# Example: run scan with ID abc123
python scripts/run-scan-runner.py abc123

# Or via environment variable
VEGA_SCAN_ID=abc123 python scripts/run-scan-runner.py

When to use: when you have a specific failing scan and want to debug its execution with local logging.

Database migrations

python scripts/run-db-migrations.py

Applies any pending SQL migrations to the Postgres database configured in VEGA_DATABASE_URL. Safe to run multiple times — it skips migrations that have already been applied.

When to use: after pulling code that contains new migration files, or after switching to a fresh Postgres database.

Maintenance jobs

python scripts/run-maintenance.py

Runs maintenance tasks: cleanup of stale artifacts, old sessions, orphaned records. Use --once to run all jobs once and exit rather than looping.

python scripts/run-maintenance.py --once

When to use: when you want to clean up local state or test that the maintenance logic works correctly.

Build Codex runner image

scripts/build-codex-runner-image.sh

Builds the vega-codex-runner:latest Docker image from docker/codex-runner/Dockerfile. This image is used by scripts/codex-in-target-container.sh to run Codex in an isolated sandbox.

Required before running scans locally if VEGA_V16_CODEX_BIN is set to the default container script (which it is by default).

When to use: first-time setup, or after changes to docker/codex-runner/Dockerfile.