Overview

Run it locally

Halo is a monorepo: a FastAPI workflow engine and a Next.js operator UI. Here is how to bring both up.

Prerequisites

Python 3.12 and Node.js 18+.
A TrueFoundry account with the AI Gateway configured (virtual models, MCP servers, guardrails). See TrueFoundry + Bedrock.

Run the API

The workflow engine lives in apps/api (FastAPI + SQLModel/SQLite). It reads its config from apps/api/.env.

cd apps/api
python -m venv .venv && source .venv/bin/activate
pip install -e .
uvicorn app.main:app --reload --port 8000

The API serves interactive OpenAPI docs at http://127.0.0.1:8000/docs.

Run the web app

The operator UI lives in apps/web (Next.js 15 / React 19 / Tailwind 4). It talks to the API and renders the landing page, the dashboard, and the incident war room.

cd apps/web
npm install
npm run dev   # http://127.0.0.1:3000

Run a single web dev server at a time. Two next dev processes share the same .next cache and can corrupt it.

The demo incident

A seed script creates a deterministic incident sitting at the approval gate, so you can open it and click Approve to watch the executed → verified flow:

cd apps/api
./.venv/bin/python scripts/seed_live_approval_demo.py

Re-run it to reset the incident — clicking Approve consumes it. Then open/incidents/inc_demo_approval in the web app.