/remote-compute-ssh

name: remote-compute-ssh
description: Evaluate and use SSH Remote Compute before choosing where to run GPU, high-memory, parallel, batch, model-inference, bioinformatics, or other long-running scientific work; supports short remote commands and asynchronous jobs with automatic harvest and analysis.
license: Apache-2.0

This skill covers remote compute over SSH, including direct execution and Slurm submission: listing hosts, creating handles, running short remote commands (callCommand), reading/writing host knowledge docs, and the full async job lifecycle — submit → save `job_id` → read non-blocking snapshots by that ID → harvest → analysis turn → publish artifacts.

**Where host.compute runs:** `host.compute` lives ONLY on the control-plane REPL kernel — run every example below with the `repl_execute` tool (JavaScript), the same kernel that hosts `host.mcp`. The `python`/`r` data kernels have NO `host.compute` (SSH and approvals stay outside the sandbox workspace); calling it from a python/r cell will fail with `host.compute is undefined`.

Choose an execution location

Only Compute Hosts enabled for this Session are visible or callable. Discover them in one catalog; each entry has role `selected` or `available`. A non-empty selected pool is an execution instruction: run tool-backed task work on one or more selected hosts as the task requires. The pool has no priority and does not imply automatic multi-host scheduling. If no host is selected, choose from the available entries. Read `details()` only for candidates that need closer evaluation.

Never guess or reuse a provider id absent from the catalog. A user naming a disabled host does not make it callable; explain that it must first be enabled for this Session. If no eligible host is usable, explain the blocker and ask the user how to proceed.

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

Each list item is a compact summary with `provider_id`, `display_name`, `shape`, `execution_mode`, `status`, and `role` (`last_probe_ok`, `probe_failed`, or `not_probed`). `last_probe_ok` means the most recent persisted Probe succeeded; it does not assert live connectivity. Knowledge documents and resource probe snapshots are deliberately excluded from discovery results.

API reference

// List this Session's enabled hosts as one role-bearing compact catalog
const hosts = await host.compute.listHosts()

// Compatibility discovery names remain available; both still hide disabled hosts.
const visibleHosts = await host.compute.listRegistered()
const selectedHosts = await host.compute.listPreferred()

// Create a handle to a specific host (no network call)
const c = host.compute.create('ssh:<alias>')

// Run a short remote command (throws on approval_denied / host_unreachable / timeout)
const result = await c.callCommand('<shell command>', '<one-line intent for the approval card>', {
  loginShell: true, // default: true — runs login profiles, then readable ~/.bashrc, before this command
  timeoutSeconds: 60 // optional — the host applies its own default (60s) when omitted
})
// result → { exit_code, stdout, stderr, truncated }

// Read the persisted operation instructions and the independent resource probe snapshot.
// doc is always the exact saved text (including '' before instructions are saved).
// probe is explicitly null when this host has never been probed.
const info = await host.compute.details('ssh:<alias>', { mode: 'read' })

// Append a note to the persisted host knowledge doc (agent writes; 32 KB cap enforced).
// Append changes only doc; it never copies or changes probe observations.
await host.compute.details('ssh:<alias>', {
  mode: 'append',
  text: '\n## Note\nlearned X on <date>'
})

// Alternatively, replace the entire host knowledge doc. Read again before replacing,
// especially if you appended above: oldText must match the persisted doc exactly.
const latest = await host.compute.details('ssh:<alias>', { mode: 'read' })
await host.compute.details('ssh:<alias>', {
  mode: 'replace',
  text: '<new full doc>',
  oldText: latest.doc
})

Treat `doc` as operation instructions and durable host knowledge. Treat `probe` as a dated observation: resource values may change, and detecting a scheduler does not authorize submitting a job or select an account, partition, or queue. On a document mismatch or `details_conflict` error, read again and merge your draft with the latest document before retrying. A resource-only probe refresh does not change `doc` or cause a replacement conflict. After writing, read again to verify the saved contents. A successful append or replace result is only `{ ok: true }`. The write result does not contain `doc` or `probe`; always read again to verify the exact persisted `doc` rather than reading fields from the write result.

With `loginShell: true`, the remote Bash login profiles run first and then Open-Science attempts to source `~/.bashrc` when it is readable. A `.bashrc` can deliberately return early for non-interactive shells, so variables declared after such a guard are not available. A missing `.bashrc` is a no-op. Set `loginShell: false` to run the command without either initialization step. Initialization failures are reported through the normal command result/error behavior.

API reference (async jobs)

Use `submitJob` for long-running computations (minutes to hours). It returns immediately with a `job_id`; the job runs on the remote host in the background. When the job finishes, the app automatically harvests the outputs and initiates a new analysis turn if you have not already read the terminal result. Save the exact `job_id` from the submission result in your working context; there is intentionally no historical Job scan for rediscovering it. Status and result reads use only that saved ID and return non-blocking local