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:

{
  "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.