Erie Remote Ssh

Erie Remote SSH

Core Rule

Discover configured servers first, validate locally second, keep built-in file operations inside workdir, and connect only when the user or the requested workflow explicitly requires real SSH access.

Trigger Policy

Use this skill for conservative remote SSH work in FPGA, RTL, Verilog/SystemVerilog, HLS, C++/Python, neural network, GPU acceleration, FPGA acceleration, application testing, and skill testing workflows when the user explicitly needs SSH or remote server operations.

Use it to discover, add, or list SSH servers; parse and validate server-list JSON; inspect key-based and passwordless SSH readiness; check the remote ~/workspace; operate files inside workdir; review and execute request files for remote writes or commands; troubleshoot SSH failures; and collect remote inventory.

Do not use it for purely local development, local file editing, ordinary FPGA/RTL/HLS/GPU discussion without remote intent, non-SSH protocols, or tasks that require directly modifying ~/.ssh or bypassing request review.

Update / Reports Preservation

Before updating or replacing this skill from GitHub, a local directory, a release artifact, or another source, use scripts/install_skill.py so the existing installed skill is backed up under ${CODEX_HOME:-~/.codex}/skill_backups before installation. Never delete or overwrite the user's installed .settings/server_list.local.json, .settings/server_list.local.json.bak.*, or reports/ content; the installer must report preserved_hash_verified: true, and failed copies must restore the backup instead of leaving a partial install. Preserve reports by default unless the user explicitly confirms cleanup. reports is a local runtime artifact root and is not managed by git. Bundled defaults keep requests, downloads, jobs, and validation temp runs under reports; root-level out, remote-validation-bundles, requests, downloads, or tmp directories next to erie-remote-ssh are not normal output from this skill. Root-level dist/ is reserved for release builds.

Use scripts/remote_ssh.py for deterministic operations whenever possible:

python \scripts\remote_ssh.py list --settings 
python \scripts\remote_ssh.py discover --settings 
python \scripts\remote_ssh.py ssh-config-discover --settings 
python \scripts\remote_ssh.py choices --settings 
python \scripts\remote_ssh.py choices --settings  --host 
python \scripts\remote_ssh.py configure --settings  --interactive
python \scripts\remote_ssh.py add-server --settings  --interactive
python \scripts\remote_ssh.py update-server --settings  --server  --interactive
python \scripts\remote_ssh.py configure-key --settings  --server  --interactive
python \scripts\remote_ssh.py project-init --settings  --server  --project  --interactive
python \scripts\remote_ssh.py project-show --settings  --server 
python \scripts\remote_ssh.py setup-key --settings  --server 
python \scripts\remote_ssh.py check --settings  --server 
python \scripts\remote_ssh.py workspace-check --settings  --server 
python \scripts\remote_ssh.py file-list --settings  --server  --path 
python \scripts\remote_ssh.py request-upload --settings  --server  --local  --remote  --reason 
python \scripts\remote_ssh.py request-command --settings  --server  --reason  [--detached --task-purpose ] -- 
python \scripts\remote_ssh.py run-request --settings  --request  --execute
python \scripts\remote_ssh.py command --settings  --server 
python \scripts\remote_ssh.py exec --settings  --server  -- 
python \scripts\remote_ssh.py command --settings  --ssh-alias 
python \scripts\remote_ssh.py exec --settings  --ssh-alias  -- 
python \scripts\remote_ssh.py exec-detached --settings  --server  --reason  [--task-purpose ] -- 
python \scripts\remote_ssh.py status --settings  --server  --job 
python \scripts\remote_ssh.py tail-log --settings  --server  --job 
python \scripts\remote_ssh.py resolve-job --settings  --job  --decision 
python \scripts\remote_ssh.py scan-software --settings  --server 
python \scripts\remote_ssh.py software --settings  --server  [--name ]
python \scripts\remote_ssh.py inventory --settings  --server 

Hard Checkpoints

Execute these checkpoints in order. Do not skip a checkpoint unless it is irrelevant to the user's requested task.

1. Read settings: prefer user-provided --settings; otherwise use the skill's default settings.
2. Discover configuration: run discover before assuming a server list or usable SSH target exists. If the server list is missing and discover reports ssh_config_fallback_available: true, use ssh-config-discover to show read-only OpenSSH aliases; --ssh-alias targets are temporary and must not be written back automatically.
3. Choose configuration mode before changes: before adding or modifying server configuration, fixing a missing private key, repairing failed passwordless SSH, creating an initial server list, or handling a list with no enabled servers, ask the user in the conversation whether they want manual instructions, the guided configuration script, or cancellation. Do not launch configure --interactive, add-server --interactive, update-server --interactive, or a platform wrapper until the user explicitly chooses guided script configuration. Do not launch configure-key --interactive until the user explicitly chooses guided script configuration for key-only repair.
4. Present choices: if the server list exists and the user has not already named a server, run choices and show every selectable server grouped by category and function; wait for the user to choose an id or name before remote access. If the user names only a host/IP, run choices --host ; when multiple logins exist for that host, ask which id or port to use before connecting. If only one enabled server exists, still present it and confirm unless the user already selected it.
5. List targets: use list for compact tabular inspection; use --all only when disabled servers matter.
6. Prepare keys when needed: run setup-key to inspect local key files. If the private key is missing for an existing server, or workspace-check / exec -- echo ok fails with Permission denied, publickey, or another key-based authentication error, ask whether to run the guided key-only repair flow. configure-key --interactive only changes key_name and validation caches after successful verification; it must not change host, port, username, workdir, enabled, category, functions, or notes. For full server edits, use configure --interactive only after explicit user choice.
7. Check target: run check before any command, exec, or inventory operation.
8. Resolve project workdir: if the task belongs to a local project, use project-show to confirm whether .settings/project.local.json or project.json is active. Use project-init --interactive before relying on a new project workdir; it checks the remote directory and asks whether to reuse, rename, timestamp, or cancel when a collision exists.
9. Scan software: add-server --interactive runs a mandatory read-only software scan for enabled servers; use scan-software to refresh cached tool availability.
10. Check workspace: run workspace-check after passwordless SSH is ready. Without project context it backs up the selected server-list JSON, writes validation and workspace_check, and refreshes cached software_scan. With project context it uses the project effective workdir, writes project workspace status to the project config, updates global SSH validation, and refreshes global software_scan.
11. Read directly: file-list, file-stat, and file-download may run directly after checks.
12. Request writes: use request-upload, request-mkdir, request-delete, or request-command before modifications or arbitrary commands. For long Vitis, Vivado, Vitis HLS, build, emulation, or board-run commands, prefer exec-detached or request-command --detached --task-purpose so status and tail-log can take over after local SSH timeout boundaries.
13. Memory gate before heavy writes: run-request --execute for uploads, detached run-request, and direct exec-detached now wait on the remote memory gate before continuing. If remote used memory reaches the configured threshold, upload/detached start is paused and a local heartbeat is written under reports/jobs/heartbeats.
14. Residual detached jobs: every server-targeted command entry checks local detached-job manifests first. Residual automated_test jobs are terminated automatically; residual user_initiated jobs block the new command until the user resolves them with resolve-job --decision preserve|terminate.
15. Execute explicitly: use run-request --execute only after reviewing the request and risks.
16. Review output: inspect warnings, redaction, side effects, failures, memory-gate waits, and residual-job actions before reporting results.

Sensitive Output

Default output is redacted. Use --show-sensitive only when the user explicitly needs runnable connection details.

command defaults to a redacted SSH command shape. Add --show-sensitive to print a runnable command.

--accept-new-host-key may update the user's SSH known_hosts file. Do not use it unless the user explicitly accepts that external side effect.

If the requested server target, write action, host-key change, or other sensitive side effect is ambiguous, ask the user before connecting or executing.

Remote Execution

exec runs the provided command through the remote user's shell after entering the effective workdir. The effective workdir is the active project workdir when a local project config is discovered, otherwise the server-list workdir. It does not make arbitrary remote commands safe. Prefer request-command plus run-request --execute for engineering workflows that need review. exec --ssh-alias is a temporary OpenSSH-config fallback mode and does not use a server-list workdir.

exec-detached starts a reviewed long-running command under the effective workdir, writes a local job manifest under reports/jobs, and returns a job id for status and tail-log. Use --task-purpose automated_test for disposable automation and --task-purpose user_initiated for work that may need explicit preservation. Before detached startup, the helper checks the remote memory gate and writes a local heartbeat packet while waiting. Treat a synchronous SSH timeout as a transport boundary, not proof that the remote command failed; detached jobs provide the evidence needed to decide whether to wait, inspect logs, rerun, or later resolve-job.

File Operations

Built-in file operations accept remote paths relative to workdir only. They reject absolute paths, drive paths, and parent traversal. Write, delete, upload, mkdir, and arbitrary command operations require request files and run-request --execute.

Uploads also validate the local source. request-upload --local must resolve inside configured paths.upload_roots, which defaults to ${project_root}. In a source checkout, ${project_root} resolves to the repository root; in an installed or release copy, it resolves to the skill root so the default upload boundary does not widen to the whole Codex home. Use a custom settings file with explicit upload roots, such as a current workspace or data directory, before uploading files outside the skill project. Sensitive local sources such as .codex, .ssh, private keys, .env, known_hosts, authorized_keys, and system directories require --confirm-sensitive-local-upload on both request-upload and run-request --execute, plus a clear --reason. run-request --execute for uploads now enforces the remote memory gate before the actual SCP step.

Configuration Discovery

discover only inspects configured JSON and, when the server list is missing, reads configured OpenSSH Host aliases as a fallback hint. It does not scan networks, probe unknown hosts, generate SSH keys, modify SSH config, or create server records. ssh-config-discover excludes wildcard/pattern aliases and redacts HostName/User/Port/IdentityFile unless --show-sensitive is explicit.

configure --interactive is the configuration gate. Use it after the user has explicitly chosen guided script configuration in the conversation. Inside the CLI, the user must explicitly enter script, manual, or cancel; pressing Enter does not choose a default. Guided mode can initialize a missing list, add a server, update a server, and generate a local SSH key only after showing the target path and receiving explicit confirmation. It does not install public keys on the remote host.

choices is a local selection gate. It groups enabled SSH servers by category, shows explicit or inferred functions, cached software availability, validation status, and workspace status. Use choices --host when the user gives an IP or hostname and the same machine may have multiple usernames or ports. It does not connect, scan, or write the server list.

add-server --interactive uses a grouped wizard for connection, key/workdir, and metadata fields, then shows a redacted summary before writing. It supports category, semicolon/comma-separated functions, and notes. Treat it as a lower-level maintenance or validation entry point; for normal agent-guided configuration, use configure --interactive after the user chooses guided script mode. When the host already exists, the prompt lists existing usernames and ports so the user can confirm another login entry or cancel a duplicate. If the configured private key is missing, it prompts to generate the key, save the server disabled, or cancel before writing an enabled unusable entry. The server entry is retained with software_scan.status: failed if the SSH scan cannot complete.

update-server --interactive uses a field menu. Choose show, one editable field, all, done, or cancel; only selected fields are prompted. done shows a redacted summary and requires save_server_record before writing. configure --interactive lists configured servers with numbers before update, and accepts a number, id, or name. Editing host, port, username, key_name, or workdir clears validation/workspace/software caches; editing only metadata preserves them. Connection/key/workdir changes and enabling a server use the same missing-key gate as add-server and refresh cached software for enabled connection changes; metadata-only edits do not force a key check or scan.

configure-key --interactive repairs an existing entry's local key reference and passwordless validation only. Use it after the user explicitly chooses guided script configuration for a missing private key or key-based authentication failure. It may prompt for key_name, generate a local Ed25519 key after explicit confirmation, and print authorized_keys guidance. It does not install public keys remotely, run ssh-copy-id, rewrite SSH client configuration, or write the server list until the candidate key verifies the remote workdir. After verification succeeds, it backs up the selected server-list JSON and writes only key_name, validation, workspace_check, and refreshed software_scan.

Default configuration reads and writes skill-local .settings/server_list.local.json through assets/defaults.json. Use assets/server_list.template.json as the non-sensitive template, or use --config when a user provides an explicit alternate server-list JSON. If a legacy config/server_list.local.json exists, the helper migrates it into .settings/ before normal execution and deletes the old file after a successful write and validation pass. If the caller explicitly passes a legacy settings file whose paths.default_server_list still points at config/server_list.local.json, the helper automatically corrects it to .settings/server_list.local.json for this run and prints a migration warning.

`add-

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Eriemon
• Source: Eriemon/remote-ssh
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.