Connect the local Python companion

The browser viewer opens, renders, navigates, and annotates slides without Python. Install this optional companion only when you want to execute visual workflows or run Python tooling. The companion runs on your workstation, binds to loopback (127.0.0.1), and prints a short-lived pairing code.

Requirements

• Python 3.10 or later (the project declares requires-python = ">=3.10").
• A supported desktop browser at a secure origin. Local development can use http://localhost; remote viewer previews require HTTPS and an explicitly configured exact origin.
• Linux/POSIX is the validated workflow-runtime environment. Windows process/resource limits and descendant cleanup are not supported by this V1 runtime. macOS/GPU resource behavior is not validated.
• NumPy is needed for array/workflow execution. WSI decoding for the visual workflow is performed in the browser, not by opening the user's slide path in Python.

Install in an isolated environment

From the Python SDK checkout:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e '.[workflows]'
.venv/bin/microscope --help

[workflows] adds NumPy to the SDK. It does not install OpenCV, PyTorch, ONNX Runtime, or model weights. Install each optional node pack separately into its own environment; this avoids dependency conflicts and keeps model runtimes out of the core SDK.

For SDK commands that open WSIs directly from Python, install the optional imaging dependencies and an OpenSlide native library as appropriate for your platform. The SDK quickstart uses:

.venv/bin/python -m pip install -e '.[imaging]'
.venv/bin/python -m pip install openslide-bin

openslide-bin is one supported native-library route; use a system OpenSlide installation if that is how your environment is managed. These Python imaging dependencies are not required by the browser viewer or by the companion's browser-captured workflow inputs.

Start the companion and configure the viewer origin

Start the local process and allow only the exact viewer origin:

.venv/bin/microscope serve --origin http://localhost:5173

The process prints the pairing code and listens on loopback port 8765 by default. If the viewer uses another host, port, or HTTPS domain, pass that full origin exactly (scheme, host, and port where applicable):

.venv/bin/microscope serve \
  --origin https://your-viewer.example.ts.net

Do not configure a wildcard origin. In the viewer, open Workflow, expand Connect Python, enter the current code, and approve local-network access if your browser asks. A pairing grants that viewer origin access to run trusted Python in the user's account context. Re-pair after restart when the session expires.

If you register a local pack with microscope nodes register after starting the process, restart the companion and reconnect to refresh its node catalogue. See Python node packs.

How a workflow moves image data

1. The viewer's browser owns the open slide File and decodes it through OpenSlide WebAssembly.
2. WSI Region selects a viewport, selected ROI bounding rectangle, explicit level-0 rectangle, bounded overview, or a tile in a supported whole-slide run. The browser reads/resamples that bounded region using the slide's actual X/Y MPP when physical resolution is requested.
3. After pairing, the browser sends the selected image array and a bounded geometry descriptor over an authenticated HTTP request to its own loopback companion. The companion does not receive arbitrary browser file paths or the complete source file. The workflow image payload goes directly from the local browser to the local companion; it is not sent through a cloud service by this path.
4. The engine validates input types/geometry, runs installed nodes locally, and returns terminal outputs. Masks/probabilities/labels can be added as viewer layers; tables, RGB/gray arrays, and other supported outputs have their corresponding local export paths.

The companion does not gain arbitrary access to files selected in the browser. A node only sees the arrays and explicit parameters supplied by the validated graph. A separate MCP process can read paths beneath its configured --root, but that does not grant the workflow companion access to the browser's open slide.

Run and keep a result

Open a slide, build or load a workflow, verify the Python status is connected, and choose Run. The Workflow console shows per-node state, progress, errors, and a bounded tail of Python output. Select a completed raster terminal and use Add to Layers. The layer remains in the browser until saved with the slide workspace. Workflow drafts and exported workflow JSON store graph settings, not WSI pixels, results, transient runtime input IDs, or private model-weight paths.

To stop a job, choose Cancel in the workflow controls. Closing the workflow dock alone does not cancel it; closing/replacing its source slide cancels its active job. Completed results are not copied to a public server.

Troubleshooting

Symptom	Check
Viewer cannot discover the companion	Ensure microscope serve is still running and use the exact current pairing code. The process binds to loopback, not an externally reachable network interface.
Pairing/preflight is rejected	Confirm --origin exactly matches the viewer's scheme, host, and port. Check browser local-network permission and workstation firewall. Do not use a wildcard origin.
Workflow tab says a node pack is unavailable	Register/install that pack into a separate runtime and refresh/reconnect. SDK installation alone does not install algorithm packs.
No module named numpy	Install the SDK [workflows] extra into the companion environment. Pack dependencies belong in that pack's selected interpreter.
Source input or layer is unavailable	Re-select the source region or output layer from the current open slide and retry. Source IDs and layer snapshots are local per-run values, not portable workflow fields.
Physical source resolution rejected	Ensure X and Y MPP metadata are both present/positive and that requested working MPP is not finer than native sampling. Objective-power metadata is not substituted.
Job was cancelled or hit a bound	Reduce the region/tile/output size or split the analysis. The companion enforces node, memory, request, and deadline bounds; it does not return partial outputs as if complete.

Verify your installation

From this repository's root:

.venv/bin/python -m unittest discover -s tests -v

This runs the SDK's local workflow, companion, authoring, and file-contract tests. Browser-to-loopback HTTPS compatibility is separately exercised by the repository's documented Playwright companion tests; running those extra tests requires their browser and local TLS test setup.

Next: Create your first tissue mask, write a custom Python node, and author graphs through MCP.