# Compute Env Setup

> Set up and validate a reproducible Python or R environment on a Wisp execution context. Use for a selected local, WSL, or direct SSH context when installing scientific packages, configuring caches, recording interpreter activation, or producing an environment smoke test. Do not use for scheduler clusters or managed cloud providers that Wisp cannot track yet.

- Skill: `xuzhougeng/compute-env-setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add xuzhougeng/compute-env-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xuzhougeng/compute-env-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: xuzhougeng (https://skillmd.com/u/xuzhougeng)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/xuzhougeng/compute-env-setup

---


# Set up a compute environment

Treat the selected and probed `ExecutionContext` as authoritative. Wisp
currently supports `local`, `wsl:<distro>`, and direct `ssh:<alias>` contexts;
it does not expose an authenticated provider SDK inside Python.

## Plan the environment

Define before installing:

- Python or R version;
- ordered conda/pip/R package phases with important pins;
- required CUDA capability and minimum VRAM;
- cache variables and durable weight locations;
- import checks, CLI checks, and one seeded representative workload;
- the exact activation command later Runs must include.

Use `references/envs_reference.md` for package-order and cache examples, but
replace container-specific paths with paths valid on the selected context.

## Direct SSH workflow

1. Require a selected `ssh:<alias>` context with a recent Probe result. Respect
   recorded GPU, privilege, interpreter, conda/mamba, module, and scheduler
   capabilities.
2. If a scheduler is detected, stop. Do not install or run long work on a
   shared login node; Wisp needs a scheduler-aware Run backend first.
3. Use at most a few bounded read-only `shell` commands to confirm free space,
   existing environments, and cache paths.
4. Write an idempotent project script such as
   `runs/setup-<environment>.sh`. It must use user-writable paths, fail fast,
   activate the environment explicitly, run all smoke checks, and write a
   small JSON manifest only after validation succeeds.
5. Submit the setup script through one persisted Run:

```json
{
  "context_id": "ssh:gpu-box",
  "title": "Set up singlecell environment",
  "command": "bash setup-singlecell.sh /home/me/envs/singlecell /home/me/wisp-env-manifests/singlecell.json",
  "timeout_secs": 14400,
  "input_paths": ["runs/setup-singlecell.sh"],
  "output_specs": [
    {
      "glob": "ssh://gpu-box/home/me/wisp-env-manifests/singlecell.json",
      "kind": "environment-manifest",
      "residency": "remote"
    }
  ]
}
```

6. Replace all example paths with probed absolute paths. Call `monitor_run`
   when waiting is useful (again after `wait_interrupted`; do not resubmit).
   Use one `get_run` snapshot later or `cancel_run` when requested.
7. Record the validated activation command, versions, cache paths, GPU witness,
   date, and known limitations in a normal project file such as
   `environments/<context>/<name>.md`. This file is documentation, not a hidden
   resolver.

## Setup-script requirements

- Make repeated execution safe: reuse a matching environment or stop with an
  actionable version mismatch.
- Keep pip install phases ordered; a later dependency resolver must not silently
  replace pinned torch, CUDA, JAX, NumPy, or compiled extensions.
- Never use `sudo` unless the Probe explicitly records suitable privilege and
  the user authorizes it. Prefer conda packages, modules, or user paths.
- Put multi-gigabyte weights in durable remote storage. Populate them with the
  model's real loader, verify non-empty content and completion markers, then run
  a representative inference witness.
- Write the manifest atomically only after imports, GPU visibility, and the
  representative workload pass.

## Local and WSL boundary

Local and WSL Runs are currently capped at 300 seconds and do not support
`input_paths`. Use `local-env-setup` for normal interactive setup. Use
`run_in_context` only for a bounded command that finishes within that limit and
writes outputs to host-visible project paths.

## Unsupported backends

Wisp has no scheduler, Modal, RunPod, cloud Batch, container-service, or managed
endpoint execution context today. Do not invent a provider id or hide those
lifecycles inside an SSH submission command. Explain the boundary or use a
dedicated direct SSH host until a backend implementing submit, poll, cancel,
recovery, secrets, and artifact harvest exists.