Configuration¶

Most of biopb is configured for you by the installer. This page collects the settings you're most likely to touch — chiefly which data server to use and where things live on disk.

Environment variables¶

Variable	What it controls
`BIOPB_TENSOR_URL`	The data server to connect to (e.g. `grpcs://lab-data:8815`). Outranks your control plane — set it only when you mean to bypass your own data plane, and pair it with a token.
`BIOPB_TENSOR_TOKEN`	Access token for the data server named above (see Security).
`BIOPB_UPSTREAM_TENSOR_TOKEN`	Token for a remote server you mounted as a `tensor-server` source in `biopb.json`.
`BIOPB_CONTROL_HOST`	Host the control plane binds and clients look for (default `127.0.0.1`).
`BIOPB_CONTROL_PORT`	Port the control plane listens on (default `8813`).
`BIOPB_BASE_PORT`	Containers only. Base port inside the container (default `8810`); the ports below are derived from it. Locally, use the `--base-port` flag instead.

Set these before launching your agent or napari, for example:

Linux / macOSWindows (PowerShell)

export BIOPB_UPSTREAM_TENSOR_TOKEN=your_secure_token

$env:BIOPB_UPSTREAM_TENSOR_TOKEN = "your_secure_token"

Environment variables last only for the session

Both forms set the variable for the current terminal only. To make it stick, add the export lines to your shell profile (~/.bashrc, ~/.zshrc), or on Windows use Settings → System → About → Advanced system settings → Environment Variables.

When running a tensor server yourself, additional variables (BIOPB_TENSOR_TOKEN, CONFIG_FILE) apply on the server side — see Data (tensor) servers.

Ports¶

Port	Used by
`8813`	Control plane — the web origin you visit (dashboard, viewer, admin)
`8814`	Tensor server HTTP sidecar (API only; the control plane proxies it)
`8815`	Tensor server gRPC / Arrow Flight data API
`50051`	Algorithm server gRPC (default)

8813 is the one to remember — everything you open in a browser goes through it. The control plane reverse-proxies the other two, so on a normal install you never visit 8814 directly.

If a default port is already in use — common on shared machines or HPC nodes — shift all three at once with a single number:

biopb control start --base-port 9000    # control 9003, sidecar 9004, gRPC 9005

A control plane that moved publishes where it landed, so status, stop, logs, and your agent follow it without being told. In a container, the same convention is spelled BIOPB_BASE_PORT.

File locations¶

Biopb uses the same layout on every platform — it doesn't use Windows' AppData. The ~ below is your home directory, so on Windows ~/.config/biopb/biopb.json means C:\Users\<you>\.config\biopb\biopb.json.

Config files¶

Both files live side by side in ~/.config/biopb/, but they are never merged — each is owned and validated by exactly one process:

Data server config: ~/.config/biopb/biopb.json — settings for the tensor server (data sources, cache, remote upstreams). Override the path with the CONFIG_FILE env var. JSON is the only supported format: a legacy biopb.toml is refused with a message naming the conversion command, biopb-tensor-server migrate-config.
Client / MCP config: ~/.config/biopb/mcp-config.json — settings for the napari client and agent bridge: the kernel, dask, and the algorithm servers your agent can reach.

Two more files live in the same directory:

~/.config/biopb/extra-packages.txt — Python packages to keep across upgrades (see Working with napari).
~/.config/biopb/kernel/*.py — your own tools, loaded into the agent's namespace at startup. The installer seeds an example, rolling_ball.py, and never overwrites your edits.

Don't confuse mcp-config.json with mcp.json

mcp-config.json is biopb's own settings file. mcp.json is the client-definition file your agent reads to learn how to launch biopb — a different file, written by biopb agents register.

Logs and cache¶

Session (kernel) logs: ~/.local/share/biopb-mcp/log/sessions/<session-id>.log — output from the kernel that runs your agent's code and hosts the napari viewer. Each agent session gets its own file. Check here if a session misbehaves.
Data server logs: ~/.local/share/biopb/log/ — when the data plane fails to start, the full server output is written here. Check it for the underlying error. You can also read it from the dashboard at http://127.0.0.1:8813/logs.
On-disk cache: Data servers lean heavily on caching to achieve fast zero-copy data transfer. But you can delete these files if you no longer need the server or want to start from scratch.

What's inside the config files¶

Data server — `biopb.json`¶

This file says what data to serve. A minimal one names a directory (directories are scanned recursively):

{
  "sources": [
    { "url": "/path/to/your/data", "monitor": true, "alias": "my-data" }
  ]
}

Give a source a friendly name with alias, and watch it for new files with monitor. A source's id is derived from its resolved URL, so the same data always maps to one catalog entry — an explicit sources.source_id is ignored with a warning.

A source can also be another biopb server, which mounts its catalog alongside your own:

{
  "sources": [
    { "type": "tensor-server", "url": "grpcs://data.mylab.example:8815" }
  ]
}

Where the server listens is not in this file

Exposure and ports are command-line arguments to biopb control start — --grpc-bind and --base-port — so that a config edit can never silently disagree with the running server. See Security.

You can declare multiple sources, override metadata per source, and tune the cache. See the tensor-server reference for the full set.

Client / MCP — `mcp-config.json`¶

The client config is a nested JSON file. It's deep-merged with the built-in defaults, so you only need to include the keys you want to change. Every section sits at the top level of the file. The entries most users touch:

Key	Default	What it does
`services.process_image_servers`	`[]`	List of algorithm server URLs to expose to your agent, e.g. `["grpc://localhost:50051"]`.
`dask.scheduler`	`"distributed"`	Compute mode: `"distributed"` (multi-process), `"threads"`, or `"synchronous"`.
`dask.num_workers`	`0` (`4` on Windows)	Worker processes for local compute; `0` lets dask pick (~CPU count).
`dask.memory_limit`	`"auto"`	Per-worker memory cap, e.g. `"4G"`.
`dask.address`	`""`	Connect to an external dask scheduler instead of spinning up a local cluster.
`dask.cache_budget`	`"1G"`	Cluster-wide chunk-cache budget, split across workers.

There is no data-server URL in this file

The control plane owns the data plane and is asked for its address when a client connects, so a configured URL could only be a second, staler answer. To reach a different server, see Connecting to a server someone else runs.

For example, to register an algorithm server:

{
  "services": {
    "process_image_servers": ["grpc://localhost:50051"]
  }
}

An unknown or out-of-range value is never fatal: biopb warns and falls back to the default, so a typo degrades rather than breaks your session.

There are many more advanced keys (operation timeouts, gRPC limits, pyramid building, kernel watchdog) that most users never need to touch; the defaults are sensible. You can also ask your agent to edit mcp-config.json for you instead of editing it by hand, or use the MCP Settings editor on the dashboard.