Local setup

Use Bun for this repository. The normal local command starts a disposable, seeded OncoBrain stack; it does not require Docker, a .env file, or model credentials just to browse the product.

Start here

Install the pinned Bun version and Node 24 or newer, then start the stack:

bun --version # 1.3.14
node --version # 24 or newer
bun install --frozen-lockfile
bun run dev

Open the application and sign in with either synthetic demo account shown on the sign-in screen. The launcher starts the database service, the web application, the draft-generation service (Eve), the local object store, and OpenObserve. It applies migrations and recreates synthetic cases and evidence on each ordinary run.

Use bun run dev --keep when you want to preserve local changes between runs. Use bun run dev --build to run production-built application services with the same disposable data. Ctrl-C stops services owned by the launcher.

Need	Command
Keep local state	`bun run dev --keep`
Run built services	`bun run dev --build`
Start only an app dependency group	`bun run dev --only app`
Omit local telemetry	`bun run dev --no-observe`
Start the documentation site alone	`bun run --cwd apps/docs dev`

The service addresses are app 3100, Celld 8787, Eve 49374, and OpenObserve 5080 on loopback. Use bun run dev --help for the complete service-selection interface.

Work in another checkout

A linked worktree loads apps/oncobrain/.env and apps/eve/.env.local from the primary checkout. Add only these overrides in that worktree when another stack is already running:

ONCOBRAIN_PORT=3101
EVE_PORT=49375

The launcher derives its other local ports and browser origins from the app port. Do not copy the full local service configuration. The generated state under .oncobrain-local-demo/, .celld/, and .oncobrain-openobserve/ is disposable and must never become application data.

Model calls

The seeded walkthrough works without a model credential until a live model request is made. Hot development defaults to the ChatGPT provider; production-shaped starts, deployments, and evaluations default to the Gateway provider. Before diagnosing a missing configured credential, run:

bun run environment:check

Local development, tests, and evals replay private LLM cassettes when an identical request is available. Use ONCOBRAIN_LLM_CASSETTE_MODE=replay to require a replay, record to refresh one, and live only when a real provider call is intended. Cassettes contain request and response text and stay ignored in the primary checkout; production does not load them.

Verify a change

Start with the narrowest useful command, then widen only when the change warrants it:

bun run format:check
bun run check
bun run lint
bun run test:fast

bun run test:integration covers persistence and shared infrastructure. bun run test:full adds the local browser check. For a built browser run, install Chromium once and then run:

bun run --cwd apps/oncobrain test:browser:install
bun run test:browser

Use bun run eval:list to see Eve evals without calling a model. Run a focused eval after changing an Eve skill, tool, instruction, or generated-output behavior.

Common tasks

Generate demo PDFs

The checked-in pack in apps/oncobrain/demo-materials/ includes synthetic patient records, two synthetic references, a walkthrough, file hashes, and the PDF theme. Demo startup loads these PDFs automatically. Use the same individual records from one patient folder for manual uploads.

After changing the source records or theme, run bun run demo:materials and commit the refreshed pack. Add --output /absolute/path to generate a separate copy. bun run fixtures:check verifies that the checked-in pack matches the generator.

The PDFs use the same source facts as demo seeding and the same fonts and colors as app exports. The theme lives in apps/oncobrain/src/config/pdf.ts; the source records live in apps/oncobrain/src/config/demo-materials.ts. Repeated generation produces identical bytes. Existing source files and export receipts retain their original bytes. Generating the pack does not start services, reset cases, or rerun AI requests.

Change a database schema

Application database access uses Drizzle through the organization Cell. Generate and review the checked-in migration; do not add feature SQL by hand.

bun run --cwd apps/oncobrain db:generate
git diff -- apps/oncobrain/drizzle
bun run --cwd apps/oncobrain db:bundle:check

Run app and Eve separately

The normal launcher is preferred. A separate built start needs a shared, high-entropy ONCOBRAIN_EVE_CHANNEL_SECRET, then one terminal for the draft-generation service (Eve) and one for the web app:

bun run build
bun run --cwd apps/eve start
bun run --cwd apps/oncobrain start

The local launcher creates its own ephemeral integration secrets; separate processes do not.

Check the running app

curl -i http://127.0.0.1:3100/healthz
curl -i http://127.0.0.1:3100/readyz

/healthz only reports a running web process. /readyz also checks configuration, the database service, the draft-generation service, schema access, intake configuration, and a bounded object-store write/read/delete probe. It is not evidence of backup freshness, restore readiness, or high availability.

Troubleshooting

Symptom	What to do
Changes disappear after restart	Start with `bun run dev --keep`. Plain `dev` resets by design.
Port is already in use	Stop the stack that owns it, or set `ONCOBRAIN_PORT` and `EVE_PORT` in this checkout.
Node is missing or too old	Install Node 24 or newer; Eve's local CLI requires it.
A model request cannot authenticate	Run `bun run environment:check`, then configure the provider deliberately.
The app is up but a workflow is unavailable	Check `/readyz` and the local launcher output; workflows need the draft-generation and database services.

See Operations and observability for telemetry and administrator diagnostics, and deployment for the supported hosted path.

Improve this page