Skip to content
Project VELAProject VELA

Getting started

VELA is a Python 3.12 backend + a React (Vite) operator console. It runs fully offline by default — no cloud keys, no live spacecraft — on a synthetic reference spacecraft (VELA-REF-1) and seeded replay scenarios.

Prerequisites

  • Python 3.12 and uv (the Astral installer/venv manager)
  • Node 22+ and npm (for the console and repo tooling)
  • Optional: Docker (for the real Neo4j/Qdrant/Postgres backends)

Install

Terminal window
# Backend — a local .venv the Makefile expects
uv venv --python 3.12 && uv pip install -e ".[dev]"


# Repo tooling / git hooks (husky), once
npm install


# Operator console
cd apps/console && npm ci

The gate: make check

One command runs the whole quality gate — the same one CI runs, in both airgap and cloud modes:

Terminal window
make check      # ruff + mypy --strict + import-linter + no-commanding guardrail + pytest
Command What it does
make demo One investigation (CELL_DEGRADATION, airgap), held for approval
make test pytest only
make eval Golden cases only (tests/golden)
make lint / make format ruff check / ruff format
make typecheck mypy –strict over vela/
make imports import-linter boundary check
make guardrail the no-commanding grep
make kg smoke-load VELA-REF-1
make bench golden benchmark harness → results/bench/<sha>.json

Run an investigation

Terminal window
python -m vela.cli scenarios                                          # list the 10 scenarios
python -m vela.cli investigate --scenario CELL_DEGRADATION --approve --replay
python -m vela.cli investigate --scenario MEMORY_SEU_STORM --detector graph --out ./out
python -m vela.cli detect --scenario WHEEL_FRICTION --method ecod     # or --method graph
python -m vela.cli sweep                                              # proactive-watchlist triage
python -m vela.api                                                    # HTTP service, docs at /docs

investigate exits 1 on a citation-integrity violation (a sev-1 that fails a pipeline); --out DIR writes <id>.md + <id>.audit.json.

Run the console against the live API

The API keeps CORS closed by default, so plain python -m vela.api is reachable by curl but not by a browser. For local full-stack development:

Terminal window
make serve      # API with CORS opened to the Vite dev origins + auth off
make seed       # POST the reference scenarios so the console has real cases
cd apps/console && npm run dev   # then pick "live service" @ localhost:8000

Console commands:

Terminal window
npm run dev | build | lint | test    # lint = eslint + tsc --noEmit; test = vitest run
npx vitest run src/api/client.test.ts # a single test file

Modes: airgap vs cloud

Mode resolves as explicit arg > VELA_MODE > airgap. airgap hard-fails if reasoning is not deterministic — it is the reproducible, sovereign default. cloud enables the real Claude reasoning path (key-gated). Every golden case and the CI smoke run twice, once per mode.

Where to go next