Installation

CoSci runs locally on macOS or Linux. It’s free and open source — you run it from the repository.

Prerequisites

Tool	Why	Install
uv	runs the Python backend + its isolated venv	curl -LsSf https://astral.sh/uv/install.sh | sh
Node.js 18+	builds the Vite frontend	https://nodejs.org
uvx (ships with uv)	runs the ToolUniverse sidecar on demand	comes with uv

No global Python/Node packages touch your system — uv manages an isolated backend venv, and ToolUniverse runs in its own throwaway uvx environment.

One-click start

Double-click start.command in Finder (or run ./start.command in a terminal). That’s it. The first run builds the frontend and seeds a profile (~1 min); every run after is instant. It then opens http://localhost:8799 with the co-scientist already wired up — no second terminal, no DevTools, no localStorage to type.

./start.command            # build-if-needed → seed → serve app + API on :8799 → open browser
./start.command --rebuild  # after you change frontend code, rebuild the UI bundle
# stop: press Ctrl-C in the launcher window

Why one URL works: the backend serves the built frontend same-origin at http://localhost:8799 (app at /, API under it), so there’s no CORS and no separate API-base step.

Two-terminal dev mode

Only needed if you’re editing the UI and want Vite hot-reload:

# terminal 1 — backend
cd backend
uv run python seed_coscientist.py               # seed example data (idempotent)
uv run uvicorn app.main:app --port 8799          # http://localhost:8799/docs

# terminal 2 — frontend (hot reload on :5173)
cd cosci-app
npm install                                       # first time only
npm run dev                                        # http://localhost:5173

Then in the browser DevTools console at http://localhost:5173, run once and reload:

localStorage.setItem('rc-api-base', 'http://localhost:8799')
localStorage.setItem('rc-data-mode', 'real')

Only the Vite dev server needs this — the one-click build bakes it in for you.

Next: wire up a provider (or stay offline), then walk the quick start.