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 26+ - 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.

From PyPI (recommended)¶

uv tool install strata-notebook
strata-notebook

This puts strata-notebook, strata, strata-notebook-tui and strata-worker on PATH in a uv-managed tool environment. The wheel ships the Rust extension and the frontend prebuilt. Plain pip install is not supported; see the uv requirement above.

Add extras in brackets, for example uv tool install "strata-notebook[mcp,tui]" for strata agent:

Extra	Enables
`mcp`	The `/mcp` endpoint a coding agent connects to. `strata agent` needs it.
`tui`	The terminal viewer: `strata watch`, `strata-notebook-tui`, and `strata agent` unless you pass `--no-tui`.
`sql`	SQL cells. Add a driver extra for each database you connect to: `sql-duckdb`, `sql-sqlite`, `sql-postgres`, `sql-snowflake`, `sql-bigquery`.
`postgres`	A Postgres metadata database for the artifact store (`STRATA_ARTIFACT_METADATA_DSN`), for several nodes sharing one store.
`azure`	The Azure Blob Storage artifact backend, and reading Azure lake tables (`adlfs`).
`s3`	Notebook `s3://` mounts (`s3fs`), and presigned build-manifest URLs (`STRATA_ARTIFACT_PRESIGNED_URLS`) from an S3 role (instance profile, ECS task role, web identity) rather than an access key pair.
`gcs`	Notebook `gs://` mounts (`gcsfs`), and presigned build-manifest URLs (`STRATA_ARTIFACT_PRESIGNED_URLS`) for the GCS artifact backend.
`otel`	OpenTelemetry tracing.
`notebook`	The cell runtime libraries (pandas, numpy, orjson, cloudpickle, matplotlib, Pillow) in Strata's own environment. A remote worker image needs it; a local server does not, since each notebook gets its own venv.

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.

Releases after 0.9.0 also publish the image as ghcr.io/bearing-research/strata:<version>; see Docker → Prebuilt image.

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.

The table assumes a source checkout, where uv run resolves each command inside the project venv. After uv tool install, drop the uv run prefix and call strata-notebook / strata / strata-worker directly.

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`), save a display output such as a plot to a file (`cell output`), execute (`cell run/test`), cancel a server run (`cell cancel`, `--server/--session` only), and author (`cell add/edit/rm/mv/annotate`, `cell pin-fetch`, `dep add/rm`) - offline against a directory or `--server/--session` against a running server. See Notebook CLI.
`uv run strata worker <action>`	Manage a notebook's workers: `ls`, `add`/`rm`/`default` (local, edits `notebook.toml`), and `add-ssh`/`rm-ssh` (provision + tunnel a worker over SSH, against a running server). See Distributed Workers.
`uv run strata agent <notebook-dir>`	One-command on-ramp for driving a notebook with a coding agent: create-or-open the notebook, start (or reuse) a server with the MCP endpoint enabled, open a session, write the `.mcp.json` + `CLAUDE.md` the agent needs, and attach the TUI (skip it with `--no-tui` and watch in the web UI instead). Then run `claude` in the notebook directory to drive it live. Needs the `[mcp]` extra, plus `[tui]` unless you pass `--no-tui`. See Driving a notebook with a coding agent.
`uv run strata export <notebook-dir>`	Render a notebook to markdown or HTML (add `--app-view` for a frozen dashboard snapshot), or write a portable snapshot zip with `--to snapshot`. See Export.
`uv run strata import <file>`	Convert a Jupyter `.ipynb` into a Strata notebook directory, or unpack a snapshot zip back into one. See Import.
`uv run strata artifact <cmd> [--artifact-dir DIR]`	Inspect the server's configured artifact store (its metadata DSN and blob backend included) without a running server, or one local SQLite store with `--artifact-dir`: `list`, `show <ref>`, `lineage <ref>` (renders model ← features ← scan ← table @ snapshot), `pull <ref> --to FILE`, `audit [name]` (registry history), `pending` (approval queue), `verify`, `gc` (collect what nothing holds, least recently used first; `--dry-run` to preview, `--max-bytes`, `--max-idle-days`, `--min-idle-seconds`). Also publishes and moves results: `publish` / `unpublish` (a link anyone can open), `promote` (copy an artifact and its chain to the team store and name it there), `export` (write a tabular artifact into an Iceberg table), `archive` (a self-contained bundle: page, bytes, manifest, README). `<ref>` is a name, `id@v=N`, or bare id.
`uv run strata migrate --to-dsn <dsn>`	Copy artifact-store metadata from SQLite to Postgres. Setting `STRATA_ARTIFACT_METADATA_DSN` alone starts an empty store; this carries an existing one across. Metadata only: blobs are configured separately.
`uv run strata apikey <cmd>`	Mint, list and revoke API keys for a server running with `auth_mode="api_key"`: `create`, `list` (never shows secrets), `revoke <id>`.
`uv run strata env gc`	Remove shared environments no notebook links to. Only relevant with the shared environment backend. See Environments.
`uv run strata watch [dir\\|--session]`	Attach the read-only terminal viewer to a live notebook session without writing any config (unlike `strata agent`). Needs the `[tui]` extra. See Terminal Viewer.
`uv run strata-notebook-tui`	Read-only terminal viewer that attaches to a running notebook session. Needs the `[tui]` extra. See Terminal Viewer.
`strata-worker --port 9000`	Start a remote worker for `# @worker` cells. It binds `127.0.0.1` unless `STRATA_WORKER_TOKEN` is set (then `0.0.0.0`) or `--host` says otherwise. Run the installed binary (for example `.venv/bin/strata-worker`), not through `uv run`, whose process would keep `STRATA_WORKER_TOKEN` readable to cells. With `--connect wss://...` it binds no port and dials out to a relay instead. See Distributed Workers.

In a checkout with the venv activated (source .venv/bin/activate), you can drop the prefix too.

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 (scope is set in pyproject.toml, as in CI)
uv run ty check

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

Integration test dependencies¶

The end-to-end integration script needs a real PostgreSQL instance for its Iceberg SQL catalog. 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 script against it (starts its own server)
STRATA_CATALOG_URI=postgresql://strata:strata@localhost:5432/iceberg_catalog \
  uv run python scripts/integration_test.py --start-server

# 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.