# Cloud Instance Ops

> Use for cloud instance access diagnosis and SSH/CLI-first operations in Codex, OpenClaw, or Claude Code when the task centers on Linux server access, password or key based SSH, file transfer, service or process checks, log inspection, AWS EC2 or Aliyun ECS inspection, or diagnosing blockers such as bastions, MFA, SSO, IP allowlists, approvals, and read-only permissions. Only extend into deployment, API serving, or cloud-side mutating actions when the user explicitly asks for them.

- Skill: `agenticaiplan/cloud-instance-ops` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add agenticaiplan/cloud-instance-ops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agenticaiplan/cloud-instance-ops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: agenticaiplan (https://skillmd.com/u/agenticaiplan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agenticaiplan/cloud-instance-ops

---


# Cloud Instance Ops

## Overview
Use this skill to manage cloud servers and instances like a careful human operator **within the current authorization boundary**. Prefer SSH and official cloud CLIs. Do **not** try to bypass MFA, SSO, approval workflows, captchas, IP allowlists, bastions, or least-privilege controls.

This skill is optimized for a shared core workflow that can be reused in Codex, OpenClaw, and Claude Code. Codex-specific UI metadata lives in `agents/openai.yaml`; the operational logic stays in this `SKILL.md` plus the bundled references and scripts.

## Use this skill when
- You need to connect to a Linux instance through SSH, password SSH, `ProxyJump`, or a bastion.
- You need file transfer, service/process checks, log inspection, restart operations, or access troubleshooting on an existing instance.
- You need AWS EC2 or Aliyun ECS instance inspection or other cloud-side checks through the official CLI.
- You need to deploy a model, stand up an API, validate output artifacts, or run cloud-side mutating actions **and the user has explicitly asked for that path**.

## Required inputs
Normalize each request into these five inputs before acting:
1. **Target object**: host/IP, instance ID, region, environment, bastion
2. **Cloud environment**: generic Linux, AWS, or Aliyun
3. **Authentication method**: SSH key, password SSH, agent, AWS profile, Aliyun profile, short-lived token, SSO
4. **Restrictions**: MFA, approval, allowlist, no public route, read-only, captcha, missing CLI, shared GPU/port use
5. **Requested action**: connect, transfer, inspect, logs, restart, deploy, single-run, serve, accept, instance-check, cloud-op

Treat `deploy`, `single-run`, `serve`, `accept`, and `cloud-op` as explicit-action modes. Do not enter them from a vague “帮我看看机器” style request without confirming intent from the user prompt or environment.

If an input is missing, infer it from the environment first. Ask the user only for the minimum missing detail.

## Core operating model

### 1. Preflight
Run a lightweight local check before attempting privileged or remote work.

Typical commands:

```bash
python3 scripts/preflight.py --cloud generic --action inspect --host 10.0.0.8 --check-port
python3 scripts/preflight.py --cloud aws --action instance-check --profile prod --region ap-southeast-1
python3 scripts/preflight.py --cloud aliyun --action cloud-op --profile default --region cn-hangzhou
```

Preflight should verify only what is safe to verify locally:
- required binaries exist
- obvious credential sources exist
- referenced files exist
- target port is reachable when requested
- explicit restrictions imply `blocked`, `denied`, or `needs_user`

### 2. Execution
Use the narrowest command that answers the request.
- Prefer read-only checks before mutating actions.
- Prefer official cloud CLI for cloud-level state changes.
- For instance lifecycle operations on EC2/ECS, prefer provider CLI/API over in-guest reboot when cloud state matters.

Useful wrappers:

```bash
python3 scripts/ssh_probe.py --host 10.0.0.8 --user ec2-user --identity-file ~/.ssh/prod.pem
python3 scripts/remote_port_owner.py --port 8080
```

### 3. Restriction handling
If the environment requires human involvement, stop and return a structured handoff instead of guessing.

Common stop conditions:
- MFA / SSO / captcha required
- explicit approval required
- IP allowlist or private-network-only path not yet satisfied
- read-only permission for a mutating action
- missing cloud CLI or profile
- SSH key or bastion path unavailable
- shared port/GPU is still occupied by another workload

### 4. Handoff
Return a stable contract for both success and blocked cases so the result can be reused in later handoff, approval, or postmortem steps.

Minimum success shape:

```json
{
  "status": "ok",
  "action": "inspect",
  "target": "10.0.0.8",
  "evidence": {
    "network": {"10.0.0.8:22": "open"}
  },
  "next_step": "Proceed with the requested read-only inspection."
}
```

When blocked, return a concrete next step instead of guessing.

Expected shape:

```json
{
  "status": "blocked",
  "reason": "Target port 22 is unreachable from the current machine.",
  "next_step": "Connect through the approved bastion or ask for the current IP to be allowlisted.",
  "evidence": {
    "network": {"10.0.0.8:22": "closed"}
  }
}
```

Allowed `status` values:
- `ok`
- `blocked`
- `denied`
- `needs_user`
- `unsupported`

## Model deployment workflow
Use this workflow whenever the task is “部署模型 / 起 API / 做题面验收 / 输出文件检查” instead of plain server ops.

### Principle: single-run before serving
Always verify the underlying model or command **once** before wrapping it in an API. Do not start with service orchestration unless the user explicitly asks for service-first diagnosis.

### Recommended sequence
1. **Read-only preflight**: model path, input path, GPU/CPU, memory, ports, dependency versions, existing services
2. **Single-run check**: run one minimal inference locally or remotely and verify the base pipeline works
3. **Service deployment**: only after single-run succeeds, expose HTTP/API/worker entrypoint
4. **Example-request acceptance**: rerun the exact original `curl` or request shape from the task prompt
5. **Output artifact check**: confirm files exist, size is reasonable, type matches expectation, contents are not obviously broken
6. **Repeated-request stability**: repeat at least once to catch cold-start-only success or stale previous services

### Final acceptance checklist
Do not claim “deployed successfully” until all applicable checks pass:
- health check or docs endpoint check
- original example request check
- output artifact check
- repeated request stability check
- service log sanity check

Use the bundled scripts when helpful:

```bash
curl -fsS http://127.0.0.1:8080/docs
python3 scripts/artifact_check.py --path /data/exam/output.wav --kind audio
python3 scripts/deployment_final_check.py --url http://127.0.0.1:8080/health --repeat 2
```

## Shared runtime hygiene
In exam, benchmark, and shared-machine environments, assume the host may already have leftovers.

Before reusing a port, GPU, or task directory:
- identify the current port owner
- identify old model/server processes
- verify the endpoint is serving the intended workload, not a stale process
- verify the current environment has enough free memory/disk/GPU for the next task

Never assume “service started” means “new service is handling requests”. Always verify the response path.

## Environment isolation
Prefer one environment per task (`venv` or `conda`). If isolation is impossible:
- record key dependency versions before installation
- assess whether new packages may break existing services
- avoid in-place upgrades of shared production environments unless the user explicitly accepts the risk

## Password SSH guidance
Password SSH is common in exam or public-IP environments. Use it carefully:
- prefer a **local secure input UI** for interactive password entry
- for interactive operator workflows, default to **secure prompt + SSH master-connection reuse**
- password source priority for Codex-style tool execution:
  1. a local secure input UI (`prompt-password`) for the current task
  2. a user-provided local temp file path
  3. an environment variable that has been **verified visible** to the current tool process
- the recommended flow is: **bootstrap the SSH master session first, then execute the real remote command**
- after the first successful login, reuse the SSH master connection for the same `thread_id + user@host:port` so later commands in the same thread do not re-prompt for the password
- by default, a reused session stays alive until the operator explicitly closes it
- if the first business command fails **after** bootstrap succeeds, do not ask for the password again; reuse the existing session for retries in the same thread
- unless the user explicitly insists, do **not** ask them to paste passwords or other secrets directly into chat
- before asking the user to `export` a password variable, run a tiny visibility check first; if the current tool process still cannot read it, do **not** ask the user to repeat the export—switch to secure prompt input or a temp file instead
- never write passwords into the repo, shell history, or final logs
- distinguish authentication failure, session-bootstrap failure, and business-command failure
- prefer a reusable helper script over ad-hoc multi-layer quoting when automation is needed
- when `expect` or a similar wrapper is still required, keep the wrapper as small as possible and keep logs password-free

Recommended visibility check before relying on an env var:

```bash
if [ -n "$CLOUD_INSTANCE_PASSWORD" ]; then echo set; else echo missing; fi
```

Recommended helper usage:

1. Bootstrap a session once per thread:

```bash
python3 scripts/password_ssh.py   --host 10.0.0.8   --user root   --port 22   --prompt-password   --ensure-session
```

2. Reuse that session for real commands:

```bash
python3 scripts/password_ssh.py   --host 10.0.0.8   --user root   --port 22   --remote-command "hostname && whoami"
```

3. Close the reused session explicitly when you are done:

```bash
python3 scripts/password_ssh.py   --host 10.0.0.8   --user root   --port 22   --close-session
```

Fallback modes:
- for unattended automation: use `--password-file` or `--password-env`
- for interactive operator workflows: prefer `--prompt-password` and `--ensure-session`
- if the user wants one-shot behavior, disable session reuse explicitly with `--no-reuse-session`
- sessions are thread-scoped by default; other threads do not reuse them unless a shared `--session-namespace` is explicitly provided
## Interrupted run recovery
When the task was interrupted, never restart blindly. First check:
1. residual processes
2. listening ports
3. output file timestamps and sizes
4. last service logs
5. whether to resume or rebuild

If artifacts and downloads are already present, prefer resume. If state is ambiguous or contaminated, clean and restart only the affected slice.

## Remote script layout
For longer remote tasks, prefer a predictable work layout such as:
- `01_single_run.py`
- `02_api.py`
- `03_start.sh`
- `04_selftest.sh`
- `*.log`
- `*.pid`

Keep logs, PID files, and outputs in one task directory so interrupted runs are easy to inspect.

## Guardrails
- Never store secrets, tokens, or private keys in the repo.
- Never claim success unless a command or probe actually succeeded.
- Never attempt to bypass MFA, SSO, approval, captcha, or network policy.
- Never execute destructive or high-blast-radius actions without explicit confirmation.
- For deployment tasks, never claim success based only on “command exited 0”; validate the artifact or endpoint.

### Confirmation required
Treat these as confirmation-required even if technically possible:
- terminating or releasing an instance
- resetting or recreating disks, snapshots, images, or security groups
- firewall/public exposure changes
- forced restart/stop that may cause downtime
- any action outside the user’s stated target environment

## References
Load only the reference relevant to the current task:
- Generic Linux and SSH patterns: `references/generic-linux.md`
- AWS EC2 patterns: `references/aws.md`
- Aliyun ECS patterns: `references/aliyun.md`
- Restriction diagnosis and handoff language: `references/restricted-access.md`
- Installation and invocation checklist: `references/install-and-examples.md`
- Model deployment workflow and acceptance: `references/model-deployment.md`
- Shared runtime hygiene and environment isolation: `references/shared-runtime-hygiene.md`
- Interrupted-run recovery patterns: `references/interrupted-run-recovery.md`

## Scripts
- `scripts/preflight.py`: local preflight checks and initial status classification
- `scripts/ssh_probe.py`: non-destructive SSH connectivity/auth probe with optional bastion
- `scripts/password_ssh.py`: password-based SSH helper with secure prompt input, optional thread-scoped session reuse, and safer defaults for host key checking
- `scripts/normalize_result.py`: normalize command outcomes into the shared status contract
- `scripts/remote_port_owner.py`: inspect which local process is listening on a port
- `scripts/artifact_check.py`: verify output artifacts exist and look reasonable
- `scripts/deployment_final_check.py`: verify health/example endpoints and optional artifacts with repeat checks