Installation¶

Prerequisites¶

uv ≥ 0.8 — install via the uv installer (curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux; PowerShell installer on Windows). uv fetches a compatible Python automatically, so you don't need Python 3.12+ pre-installed. Strata refuses to start outside a uv-managed env.
Rust toolchain (rustup) — only for source builds (not Docker or uv add). Needed by maturin to compile the native Arrow IPC extension; cargo and rustc must be on PATH when you run uv sync.
Node.js 25+ — only if building the frontend from source.

Windows: source builds work via WSL2 (smoother) or native Windows (uv + rustup + Node have Windows installers). Day-to-day dev is on macOS/Linux; WSL2 is the better-trodden path.

GitHub Codespaces (zero setup)¶

Click "Open in Codespaces" on the repo and the server is running by the time the browser tab opens. No local toolchain needed. See Codespaces for what the devcontainer provisions.

Docker (Easiest)¶

No local toolchain required:

docker compose up -d --build

Open http://localhost:8765 in your browser.

From Source¶

1. Install dependencies and build the Rust extension¶

uv sync

This installs all Python dependencies and compiles the Rust extension via maturin.

2. Build the frontend (optional)¶

If you want the notebook UI served by the backend:

cd frontend
npm ci
npm run build
cd ..

The server auto-detects frontend/dist/ and serves it.

3. Start the server¶

uv run strata-notebook

Or equivalently:

uv run python -m strata

The server starts on port 8765 by default. Open http://localhost:8765.

Verify¶

curl http://localhost:8765/health
# {"status":"ok"}

Commands reference¶

The PyPI package is strata-notebook; the installed Python module and CLI binary are both named strata.

Command	What it does
`uv run strata-notebook`	Start the HTTP server (notebook UI + REST API). Same as `uv run python -m strata`.
`uv run strata run <notebook-dir>`	Headless notebook execution for CI / scheduled runs. See Headless Runner.
`uv run strata validate <notebook-dir>`	Static checks (schema, annotations, DAG) without executing. See Headless Runner.
`uv run strata new <name>`	Scaffold a notebook directory. See Headless Runner.
`uv run strata cell <action>`, `strata dag`, `strata status`, `strata dep <action>`	Agent-facing notebook tooling: inspect (`cell list/show`, `dag`, `status`), execute (`cell run/test`), and author (`cell add/edit/rm/mv`, `dep add/rm`) — offline against a directory or `--server/--session` against a running server. See Notebook CLI.
`uv run strata export <notebook-dir>`	Render a notebook to markdown or HTML. See Export.
`uv run strata import <ipynb-file>`	Convert a Jupyter `.ipynb` into a Strata notebook directory. See Import from Jupyter.
`uv run strata artifact <cmd> [dir]`	Inspect a local artifact store without a server: `list`, `show <ref>`, `lineage <ref>` (renders model ← features ← scan ← table @ snapshot), `pull <ref> --to FILE`, `audit [name]` (registry history), `pending` (approval queue), `verify`. `<ref>` is a name, `id@v=N`, or bare id.
`uv run strata-notebook-tui`	Read-only terminal viewer that attaches to a running notebook session. Needs the `[tui]` extra. See Terminal Viewer.
`uv run strata-worker --port 9000`	Start a remote worker for `# @worker` cells. See Distributed Workers.

The uv run prefix ensures the command resolves to the binary inside the uv-managed venv. If you've activated the venv (source .venv/bin/activate), you can drop the prefix and call strata-notebook / strata / strata-worker directly.

Development Commands¶

# Sync with all optional extras — matches CI. Required for the test
# suite because the harness fixtures point the per-notebook venv at
# the dev interpreter, so the dev env needs the [notebook] extra
# (orjson, pyarrow, cloudpickle) for cell-execution tests.
uv sync --all-extras

# Run all tests
uv run pytest

# Format and lint
uv run pre-commit run --all-files

# Type check
uv run ty check src/

# Start frontend dev server (hot reload, proxies to backend)
cd frontend && npm run dev

Integration test dependencies¶

A subset of integration tests needs a real PostgreSQL instance (the Iceberg SQL catalog tests). A throwaway Postgres container is shipped as docker-compose.test.yml:

# Start the test Postgres (port 5432)
docker compose -f docker-compose.test.yml up -d

# Run the integration suite
uv run pytest tests/test_*_integration.py

# Tear it down
docker compose -f docker-compose.test.yml down

The compose file is dev-only: it has no health-bound dependency on the main docker-compose.yml, and the credentials are intentionally fixed (strata/strata) for predictable local connection strings.