Remote Compute Ops

Remote compute operations

Use this skill as the provider-neutral workflow for remote GPU and server work. The provider is an adapter, not the name of the skill: RunPod, Massed Compute, and an owned/virtual server must all follow the same evidence, transport, lifecycle, and handoff rules.

When auditing this skill or designing a plan offline, do not call a provider, SSH, or bridge at all; state that live mode/identity is unproven. The read-only lookup below applies only when the user explicitly asks to inspect live remote state.

Non-negotiable transport rule

Reuse the already-created bridge or live connection before opening a new one. The purpose is reliable, rate-limit-compliant operation and avoiding unnecessary authentication attempts; never disguise traffic, evade a provider limit, rotate identities, or bypass a ban.

• Inspect the local connection registry/bridge health when one exists. A registry is a coordination hint, not proof that a tunnel is alive. Resolve the existing helper through %USERPROFILE%\\.claude\\scripts\\conn_registry.py on Windows or $HOME/.claude/scripts/conn_registry.py on POSIX when that file exists; if it is not discoverable, report “registry unavailable” instead of guessing a path.
• In a read-only investigation, do not create or re-register a bridge. If a live route is required, allow at most one explicitly authorized health probe. Record the host alias/route, registry entry age, session owner, local PID/service or control-socket metadata when available, target identity, last probe result, and whether a probe was permitted; never record credentials.
• Use one persistent provider client/session per task phase. Group compatible read-only queries and reuse keep-alive connections; do not create a client or authenticate once per command.
• The bridge probe has the stricter budget: local registry/config inspection is network-free, but SSH/tunnel health is at most one attempt total per target and phase, with no SSH retry after a timeout or connection error. The API-read retry budget in transport-safety.md does not apply to that probe.
• Batch related remote shell checks into one SSH invocation. Use ControlMaster/ControlPersist only after the exact route has passed a health check. If multiplexing fails on the platform or bridge, do not retry it blindly: use one batched command over the known working bridge.
• Do not fan out API or SSH calls merely to reduce wall-clock time. Parallelism is allowed only when the provider documents it, the connection budget allows it, and the calls cannot duplicate a mutation.
• For 429, 503, connection resets, or transport timeouts, stop increasing the request rate. Honor Retry-After, use bounded exponential backoff with jitter, and record the retry budget. See transport-safety.md.

Workflow

1. Freeze the target and read the architecture

Before a remote mutation, read the repository AGENTS.md, provider runbook, and the relevant reference. Establish:

• provider and mode (RunPod Pod, RunPod Serverless, Massed VM, or owned server);
• exact target ID/name, region, image/template, job ID, and intended outcome;
• traffic path: existing bridge, bastion, VPN/Tailscale, SSH host alias, proxy, or provider API endpoint;
• current checkout, deployment/source revision, process/job state, storage and checkpoint path, and cost/burn boundary.

Do not infer a live state from a stale handoff, old dashboard, or a command that only proves that a process exists locally.

2. Classify the provider mode before choosing a channel

Use existing target metadata first. If the mode is unknown, make one read-only control-plane lookup and classify it before touching SSH:

• RunPod Serverless: endpoint/job ID, /run//status//health, webhook, or stream. Do not try to SSH to a Serverless job.
• RunPod Pod: exact Pod ID plus a documented SSH/TCP/HTTP connection route and exact bridge/host alias. Use SSH only when the target is an actual Pod and the route is already verified; never infer Pod identity from a generic job name.
• Massed VM: instance UUID and the provider-returned SSH target, plus Massed MCP for account/instance state.
• Owned/virtual server: documented host alias and existing bridge/tunnel.

If the provider or mode remains ambiguous after that one lookup, stop and report the missing identity instead of opening a second kind of connection.

3. Reconcile read-only state through the cheapest valid path

Prefer this order:

1. existing bridge/session health and the shared connection registry;
2. one batched remote probe for host, GPU, process, disk, and durable logs;
3. one provider client session for exact inventory, billing, target, or job state;
4. a second provider call only when the first result is incomplete or ambiguous.

For long jobs, prefer durable logs, checkpoints, job events, or a webhook over a tight status loop. If polling is the only supported observation path, use one job-specific timer with a minimum interval, a maximum deadline, a request budget, and terminal-state exit. Never poll every target independently from several agents.

4. Select the provider adapter

Read provider-matrix.md and then the provider's existing detailed skill/runbook when available.

• RunPod: use the local runpod-gpu-ops skill if it is installed; otherwise use provider-matrix.md and the linked official RunPod docs for account-specific images, volumes, and lifecycle. Serverless is the default for scale-to-zero inference; a Pod is a persistent billed resource and needs an explicit reason plus a cleanup owner. Use the returned endpoint/job/pod ID as the identity for all later calls.
• Massed Compute: use the Massed MCP tools and read massed-compute-recipes.md for provider-specific recipes. Prefer read-only tools first; destructive tools may be absent from a read-only key by design. Keep the MCP session and reconcile after any timeout before considering a retry.
• Owned or virtual server: do not invent a cloud API. Reuse the verified SSH or tunnel route, batch probes, inspect the actual service/process/GPU/log state, and use the host's runbook for restart or shutdown decisions.

5. Mutate only the named resource

Launching or restarting affects cost and capacity. State the chosen target, image, quantity, region, expected hourly/per-job burn, checkpoint/storage path, and stop condition before executing within the user's request.

Termination, deletion, key removal, volume destruction, and any action that can lose unrecoverable work require exact target disclosure, explicit confirmation, the smallest possible scope, and post-action verification. A vague label such as "the idle pod" is not an exact target.