/compute-env-setup

name: compute-env-setup
description: Prepare reproducible setup instructions and validate a user-managed named software environment on an Open-Science SSH Compute Host, including direct SSH and Slurm hosts. Use when a remote job needs packages, modules, cache variables, or a repeatable activation that the host does not already provide.
license: Apache-2.0

Compute environment setup

Prepare one reproducible environment definition and instructions for one small user-managed host activation file. Open-Science resolves `submitJob(..., { environment: '<name>' })` by sourcing `~/.open-science/environments/<name>.sh` before the workload. Existing `~/.openscience/environments/<name>.sh` definitions remain readable in place. Before creating an activation, check both names: update the existing definition at its exact location; if both exist, ask the user which to retain. Never create a second activation just to rename the brand. The file contains activation only; it does not install packages when a job starts.

The environment, package caches, images, and activation file are user-managed durable resources, not Open-Science-owned components. This Skill may inspect them and prepare exact setup/removal commands, but must not execute commands that create, replace, or remove those resources. The user or host administrator runs those commands outside Open-Science and owns their lifecycle. Do not interpret the `~/.openscience` path as app ownership.

Use `host.compute` only in `repl_execute` JavaScript. Python and R data kernels do not expose it. Start from the Session catalog and do not guess a provider id:

const hosts = await host.compute.listHosts()
const selected = hosts.filter((candidate) => candidate.role === 'selected')
const candidates = selected.length > 0 ? selected : hosts

Choose the requested host, or a suitable candidate when the user left the target open. Read its knowledge and probe snapshot before changing it:

const providerId = candidates[0].provider_id
const executionMode = candidates[0].execution_mode
const details = await host.compute.details(providerId, { mode: 'read' })
const compute = host.compute.create(providerId)

If no eligible host exists, or the selected host is unsuitable, explain the concrete blocker. Do not install locally as a substitute for a requested remote environment.

Define the environment

Keep the reproducible source in the user's project: an `environment.yml`, requirements or lock file, container definition, or a short setup script appropriate to the stack. When installation must run on a compute node, include exact user- or administrator-run staging and scheduler commands in the plan; do not submit that installation through Open-Science. Do not store project package lists or secrets in the host knowledge document.

Use a logical name containing 1–64 letters, numbers, periods, underscores, or hyphens, starting with a letter or number. Its host activation file is:

~/.open-science/environments/<name>.sh

The activation file itself and every path it references must be visible at the same path on the execution node. A shared home directory satisfies this. If login and compute nodes have separate homes, copy the activation file to the compute-node home at the same path and use shared software and data paths inside it; if the host offers no durable way to do that, explain the limitation.

Prefer the host's existing environment system:

• Conda or micromamba: create the environment from the project definition, then source the shell

hook and activate it in the activation file.

• Modules: load the exact module versions in the activation file. Combine modules with a venv or

conda environment when Python packages are also needed.

• Apptainer or Singularity: installation and image creation are cluster-specific. Use an existing

shared image when possible. Do not claim that `environment` wraps an arbitrary command in a container; the activation contract only sources shell setup.

Set cache paths and bounded thread variables in the activation file when the workload needs them. Keep credentials out of it. Avoid `sudo`, system package changes, shell-profile edits, and unrequested changes to other named environments.

Before installing, use one batched, read-only probe to identify the scheduler, available environment tools, relevant modules, quotas, and shared scratch. A typical direct/Slurm probe is:

const probe = await compute.callCommand(
  'command -v conda || true; command -v micromamba || true; command -v module || true; command -v sbatch || true; printf "HOME=%s\\n" "$HOME"; printf "SCRATCH=%s\\n" "${SCRATCH-}"',
  'Inspect environment tooling',
  { loginShell: true, timeoutSeconds: 60 }
)

Ask the user only for facts the host cannot reveal, such as an allocation account, a required module family, or permission to choose among materially different package stacks.

Prepare user-owned installation and removal

Produce a bounded, copyable installation plan for the user or host administrator. When the host is configured for Slurm, explain whether the plan must be run in an interactive allocation or submitted with provider-approved `#SBATCH` directives. Do not run the bootstrap through `callCommand` or `submitJob`: package installation, image pulls, caches, and activation files outlive the Open-Science process and have no application-owned receipt or uninstall lifecycle.

Name every path the plan will create, its expected storage/network impact, and a matching idempotent removal command. Preserve shared modules, package caches, base Conda installations, and images unless the user explicitly identifies them as exclusively theirs. Never use recursive deletion on a path derived only from an environment name; give the user the exact canonical path to verify first.

The user-run plan should create the environment before installing its activation file. It should write the activation file a