English  |  中文

remote-ssh

A Codex-ready agent skill for conservative SSH-based development and test workflows.

remote-ssh turns an AI coding agent into a more careful remote-development operator. It provides trigger metadata, workflow instructions, deterministic helper scripts, configuration templates, request review flows, and validation gates for SSH work that needs explicit target selection and redacted output by default.

This repository is primarily an agent skill package. The Python CLI is included as the deterministic execution layer, but the main interface is the skill surface an agent can load and follow.

The public repository is named remote-ssh; the internal Codex skill name intentionally remains erie-remote-ssh for compatibility with existing skill triggers and prompts.

Why It Exists

Remote SSH work has sharp edges: credentials, hostnames, key paths, write boundaries, and commands that can affect another machine. remote-ssh makes the agent discover configured targets locally, present choices, validate key and workspace readiness, keep built-in file operations inside workdir, and create reviewable request files before writes or arbitrary commands.

Use it when an agent needs to work on:

• SSH target discovery, guided configuration, server-list validation, and target selection.
• Passwordless/key-based SSH readiness checks without modifying ~/.ssh.
• Guided key-only repair for existing entries through configure-key --interactive.
• Remote ~/workspace validation and bounded file operations.
• Reviewed command, upload, mkdir, and delete requests.
• Cached software availability checks for Python, Conda, CUDA, GCC/G++, CMake, Vivado, and Vitis, including multi-version scan results.
• Read-only remote inventory for development, FPGA, GPU, and application-test environments.

Skill Architecture

%%{init: {"theme": "base", "themeVariables": {"background": "#ffffff", "primaryColor": "#f8fafc", "primaryTextColor": "#111827", "primaryBorderColor": "#334155", "lineColor": "#475569", "fontFamily": "Inter, Segoe UI, Arial"}}}%%
flowchart LR
    request["<b>Agent Request</b><br/>remote intent + constraints"]
    contract["<b>Skill Contract</b><br/>trigger policy + safety rules"]
    helper["<b>Helper CLI</b><br/>discover · check · request"]
    remote["<b>Reviewed SSH Work</b><br/>redacted output · bounded files"]

    request --> contract --> helper --> remote

    classDef edge fill:#111827,stroke:#111827,color:#ffffff,stroke-width:2px;
    classDef core fill:#ecfeff,stroke:#0f766e,color:#134e4a,stroke-width:2px;
    classDef final fill:#fff7ed,stroke:#c2410c,color:#7c2d12,stroke-width:2px;
    class request edge;
    class contract,helper core;
    class remote final;

Loading

Workflow

%%{init: {"theme": "base", "themeVariables": {"background": "#ffffff", "primaryColor": "#f8fafc", "primaryTextColor": "#111827", "primaryBorderColor": "#334155", "lineColor": "#475569", "fontFamily": "Inter, Segoe UI, Arial"}}}%%
flowchart LR
    s1["<b>1. Discover</b><br/>configured JSON"]
    s2["<b>2. Choose</b><br/>redacted targets"]
    s3["<b>3. Check</b><br/>keys + workspace"]
    s4["<b>4. Request</b><br/>review writes"]
    s5["<b>5. Execute</b><br/>explicit approval"]

    s1 --> s2 --> s3 --> s4 --> s5

    classDef step fill:#f8fafc,stroke:#334155,color:#111827,stroke-width:2px;
    classDef active fill:#ecfeff,stroke:#0f766e,color:#134e4a,stroke-width:2px;
    classDef done fill:#fff7ed,stroke:#c2410c,color:#7c2d12,stroke-width:2px;
    class s1,s2 step;
    class s3,s4 active;
    class s5 done;

Loading

What's New In v1.0.0

• Replaces the older numbered remote_ssh_part* runtime split with semantic module names such as remote_ssh_config_io.py, remote_ssh_request_runner.py, remote_ssh_runtime_job_controls.py, and remote_ssh_workspace_context.py. The public entrypoints remain scripts/remote_ssh.py and scripts/validate_remote_ssh.py, but the implementation boundaries are now easier to audit and maintain.
• Expands the runtime surface around reviewed execution and bounded remote work. This release strengthens request drafts, request execution, detached job controls, workspace/project context handling, upload safety, and runtime settings resolution without widening the default redaction or workdir boundaries.
• Broadens the validation surface into smaller purpose-built suites such as docs checks, install protection, release artifact checks, wrapper script checks, static project/settings/resources checks, and remote-safety checks. The validation tree now matches the semantic runtime layout instead of the old numbered part files.
• Tightens the release and installation boundary for public publishing. scripts/build_release.py now rebuilds canonical public artifacts as dist/erie-remote-ssh-1.0.0 and dist/erie-remote-ssh-1.0.0.zip, includes both README.md and README-CN.md, excludes local-only settings, backups, reports, requests, downloads, logs, tmp/, caches, and other runtime residue, and keeps the installer contract around preserving user-local .settings/ and reports/ data.

Quick Start

Clone the repository:

git clone https://github.com/Eriemon/remote-ssh.git
cd remote-ssh

Inspect the CLI:

python .\scripts\remote_ssh.py --help
python .\scripts\remote_ssh.py discover --help
python .\scripts\remote_ssh.py list --help
python .\scripts\remote_ssh.py configure --help

Create a private server list from the non-sensitive template, or keep it outside the repository and pass it with --config:

New-Item -ItemType Directory -Force .\.settings | Out-Null
Copy-Item .\assets\server_list.template.json .\.settings\server_list.local.json
python .\scripts\remote_ssh.py discover
python .\scripts\remote_ssh.py choices

assets/server_list.template.json is only a placeholder. Real hostnames, usernames, ports, key names, key paths, inventory snapshots, and scan caches are operational data and should stay private.

Use configure --interactive as the guided configuration gate before creating or changing server entries. It asks for manual, script, or cancel mode explicitly; lower-level add-server --interactive and update-server --interactive still validate entries, preserve reviewable backups, and run the mandatory read-only software scan for enabled servers.

workspace-check writes validation and workspace status back to the selected private server list, then refreshes the cached software_scan. Run scan-software when tool installs change, and use software or software --name <tool> to inspect cached availability without reconnecting. Upload requests are restricted by paths.upload_roots, which defaults to the project root.

Use configure-key --interactive only after an explicit guided choice for an existing server whose key reference or passwordless login needs repair. Bundled request and download artifacts now default under ${skill_dir}/reports; preserve any existing reports/ directory before replacing an installed skill unless cleanup is explicitly requested.

Build And Install v1.0.0 Safely

Build the release artifact from the updated repository, validate it, and only then replace an installed skill:

python .\scripts\validate_remote_ssh.py
python .\scripts\build_release.py
python .\scripts\install_skill.py --source .\dist\erie-remote-ssh-1.0.0 --target <codex-home>\skills\erie-remote-ssh

The release source for installation must come from the rebuilt repository artifact, not from an arbitrary working copy or a temporary zip dropped into tmp/. During installation, the updater preserves local .settings/ overrides, server-list backups, and reports/ content, and it rejects artifacts that contain private config or runtime payloads.

Public Release Boundary

tmp/erie-remote-ssh-1.0.0.zip is treated as an input package for repository synchronization, not as the final public release asset. The GitHub Release asset is rebuilt from the checked-in remote-ssh repository after README updates, redaction checks, and release validation complete.

Real server lists, local settings overrides, backups, reports, request files, downloads, logs, tmp/ contents, and any other runtime or sensitive operational data must stay out of both the public repository and the rebuilt public release asset.

Repository Layout

Path	v1.0.0 role	Public/release contract
agents/	Codex skill trigger metadata.	Public and included in rebuilt releases.
assets/	Non-sensitive defaults and templates, including the server-list template.	Public and included in rebuilt releases; never replace with real host data.
references/	Operator-facing configuration, workflow, and review guidance.	Public and included in rebuilt releases.
scripts/	Stable entrypoints plus the v1.0.0 semantic runtime/validation implementation.	Public and included in rebuilt releases.
README.md, README-CN.md, LICENSE, pyproject.toml, CITATION.cff, docs/	Repository public shell and release-facing documentation.	Public repository content; preserve and update manually when importing a packaged skill core, and include the bilingual READMEs in rebuilt public releases.
.settings/	Local settings and private server lists.	Keep local only; never commit or ship in releases.
reports/	Request files, downloads, audit logs, detached-job manifests, and validation temp output.	Keep local only; preserve on install, exclude from releases.
dist/	Canonical rebuilt release output such as erie-remote-ssh-1.0.0 and its zip.	Rebuild for each release; do not treat tmp/ source zips as publishable artifacts.

Privacy Defaults

The helper does not store real account or host information in the public files in this repository. The default local configuration path is ${skill_dir}/.settings/server_list.local.json, and that file is intentionally absent from the repository. Existing legacy config/server_list.local.json files are treated as compatibility input and should be migrated forward rather than published.

Default output redacts host, username, port, key name, and key path. Use --show-sensitive only when you explicitly need runnable connection details.

Before publishing changes, check that these are not staged or committed:

• .settings/server_list.local.json
• .settings/*.bak and .settings/*.bak.*
• config/server_list.local.json
• config/*.bak and config/*.bak.*
• requests/
• downloads/
• reports/
• tmp/
• logs/
• *.log
• Private keys, real public-key comments, real IPs, real domains, real usernames, local user paths, inventory snapshots, or remote host details.

The root .gitignore covers both the new .settings/ private paths and the legacy config/ compatibility paths, but still review git status --short before committing.

Skill Usage

The Codex skill trigger remains $erie-remote-ssh.

Agents should use the deterministic helper whenever possible:

python .\scripts\remote_ssh.py discover
python .\scripts\remote_ssh.py choices
python .\scripts\remote_ssh.py configure --interactive
python .\scripts\remote_ssh.py update-server --server <id-or-name> --interactive
python .\scripts\remote_ssh.py configure-key --server <id-or-name> --interactive
python .\scripts\remote_ssh.py check --server <id-or-name>
python .\scripts\remote_ssh.py workspace-check --server <id-or-name>
python .\scripts\remote_ssh.py scan-software --server <id-or-name>
python .\scripts\remote_ssh.py software --server <id-or-name> --name vivado
python .\scripts\remote_ssh.py request-command --server <id-or-name> --reason "check current directory" -- pwd
python .\scripts\remote_ssh.py run-request --request <request.json> --execute

For detailed behavior, read:

• SKILL.md
• references/configuration.md
• references/server-list-schema.md
• references/workflows.md
• references/review-checklist.md

Validation

Run the offline validation suite before publishing:

python .\scripts\validate_remote_ssh.py

Real SSH tests are opt-in and require an explicit private server list:

python .\scripts\validate_remote_ssh.py --with-ssh --server-list <private-server-list.json>

Affiliation

Jiyuan Liu and He Li are with the School of Electronic Science and Engineering, Southeast University. They are affiliated with the Heterogeneous Intelligence and Quantum Computing Laboratory (HIQC), which works on heterogeneous intelligence, quantum computing, and related computing systems research.

Contact

Developer: Jiyuan Liu. For questions, collaboration, or academic use, contact: erie@seu.edu.cn.

Citation

This skill is maintained by authors from the Heterogeneous Intelligence and Quantum Computing Laboratory(HIQC), School of Electronic Science and Engineering, Southeast University.

If this skill helps your research, teaching, or engineering workflow, please cite it. The canonical citation metadata is maintained in CITATION.cff.

@software{liu_2026_remote_ssh,
  author       = {Jiyuan Liu and He Li},
  title        = {{remote-ssh}: An Agent Skill for Conservative SSH Workflows},
  year         = {2026},
  version      = {1.0.0},
  date         = {2026-07-03},
  url          = {https://github.com/Eriemon/remote-ssh},
  license      = {Apache-2.0},
  note         = {Agent skill package for conservative SSH-based development and test workflows}
}

License

Apache-2.0. See LICENSE.