/local-env-setup

name: local-env-setup
description: Prepare optional local Python/R runtimes, user-configured Python MCP servers, Node/scimaster-cli, and pixi for the user’s task. Reuse detected paths, configure Wisp interpreters, and apply mirrors when needed. Use for 配置环境, missing runtime dependencies, or requested local installations. For remote SSH compute use compute-env-setup.
license: Apache-2.0
tags: environment, uv, python, r, node, npm, pixi, scimaster, mirror, china, install, macos, windows, linux

Local runtime setup

Wisp starts and runs native biological tools without Python, R, uv, or Node. First-run model setup and Settings → Models show a background path check. **Cmd/Ctrl+P → Quick setup (快速配置)** reopens setup and refreshes the check. It never runs installers or creates a virtualenv. Detected executable paths are saved in the Local execution context without replacing existing choices. A found path does not establish version compatibility or installed packages.

| Task | Optional tools | |---|---| | Python analysis / persistent `python` tool | Existing Python environment; uv can help create one | | R analysis / persistent `r` tool | Rscript with `jsonlite` | | User-configured Python MCP | That server's own interpreter and dependencies | | `bear-*` literature skills | Node >= 20, npm, sci (scimaster-cli) | | Bioinformatics workflows | pixi for isolated conda/pip environments |

Start with the user's task and existing environment. Install only what it needs. Do not treat every missing optional tool as a broken installation. After changing PATH, use **Check paths again** in model settings; restart Wisp only if the GUI process needs to inherit a changed PATH. Interpreter settings can be saved directly without restarting the app.

Step 0 — Detect platform, region, and current state

Read the **Environment** section in the system prompt (`Operating system`, `Working directory`).

0a — Region / network (mirror or not)

**Before any install or `pip`/`npm`/`pixi add`, decide whether the user is on mainland China and needs mirrors.**

Signals (use several; do not rely on one):

| Signal | Mainland likely | |---|---| | User writes in Chinese and mentions 国内 / 镜像 / 翻墙 / 清华 / 阿里 | yes | | `TZ` / system timezone `Asia/Shanghai`, `Asia/Chongqing`, `Asia/Urumqi` | hint | | Locale `zh_CN`, `zh-Hans-CN` | hint | | `curl -s --connect-timeout 3 https://pypi.org/simple/` fails or >5s; tuna mirror responds in <2s | yes | | User explicitly says they are **not** in China / have full international access | no |

If **ambiguous**, ask once: "Are you on mainland China? I'll use domestic mirrors for pip/npm/conda if yes."

When **mainland mirrors apply**, set these **before** installs (user shell profile or session env):

# PyPI / uv (Python environments + pixi pip deps)
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# npm (scimaster-cli)
npm config set registry https://registry.npmmirror.com

Windows (PowerShell, persist for user):

[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")
[Environment]::SetEnvironmentVariable("PIP_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")
npm config set registry https://registry.npmmirror.com

**Pixi conda channels** (global or per-project `pixi.toml`):

[project]
channels = ["https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/"]

[pypi-config]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

Or global:

pixi config set --global pypi-config.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Alternatives if tuna is slow: Aliyun PyPI `https://mirrors.aliyun.com/pypi/simple/`, USTC conda mirrors.

If international access works, **do not** set mirrors — use defaults.

0b — Tool presence

Run with **`shell`** (PowerShell on Windows, `sh -c` elsewhere):

**Windows:**

Get-Command python,python3,Rscript,uv,node,npm,sci,pixi -ErrorAction SilentlyContinue | Select-Object Name,Source
uv --version 2>$null; node --version 2>$null; npm --version 2>$null; sci --version 2>$null; pixi --version 2>$null

**macOS / Linux:**

for c in python3 python Rscript uv node npm sci pixi; do command -v $c && $c --version 2>/dev/null; done

The optional environment panel in onboarding, model settings, and Capabilities shows detected paths. Inspect the saved Local interpreter settings before choosing another environment.

Python and R, when requested

Reuse an existing project environment when suitable. In the desktop app, `set_runtime_interpreter` saves a path on the execution context:

{"context_id":"local","language":"python","executable":"/absolute/path/to/python"}

For R, use `"language":"r"` and an absolute `Rscript` path. Users can also open **Runtime interpreters** and browse for either executable. Running REPLs keep their previous interpreter until restarted; the agent tool restarts the current conversation's matching REPL and clears its variables.

For Python, invoke the chosen executable to verify its version and install only needed packages. `python/requirements-kernel.txt` lists common analysis packages shipped as a requirements file; native biological tools require none of them. The kernel worker itself uses the Python standard library. For R, verify `Rscript -e 'library(jsonlite)'` using the chosen absolute path; install `jsonlite` in that environment if needed, then test the Wisp `r` tool.

The CLI uses an existing environment at `<workspace>/.wisp/python/.venv` if present, otherwise Python on PATH. The desktop retains these legacy fallback locations for users who already prepared them; it never creates them on launch:

| OS | Desktop venv path | |---|---| | Windows | `%APPDATA%\science.wisp-science\wisp-science\python\.venv` | | macOS | `~/Library/Application Support/science.wisp-science/wisp-science/python/.venv` | |