Let Codex inspect, transfer, and run remote engineering work through a reviewable SSH workflow.
Current version: v2.1.7
RemoteSSH is useful when a coding, build, test, simulation, or FPGA task must run on a configured SSH server. It helps Codex choose the right target, stay inside the intended remote project directory, show what will happen, and return a result you can inspect.
- Find and select one configured SSH server without scanning the network.
- Check authentication, the remote project directory, and workspace readiness before work starts.
- Inspect available tools such as Python, Conda, CUDA, GCC, CMake, Vivado, and Vitis.
- List, inspect, download, or upload project files inside the allowed workspace.
- Preview a file change or remote command before it runs.
- Start long builds, tests, emulation runs, or board tasks with a job id and log access.
- Receive a redacted summary of the target, actions, status, and produced files.
The skill keeps file work inside the selected project context, uses relative paths, and reports which upload roots and workspace checks apply before a request proceeds.
Uploads and commands are separate reviewed requests. You can see the target, workdir, reason, risk, and required confirmation before anything with an external side effect runs.
Before the first request, prepare:
- A Codex environment that can use skills.
- Python 3.10 or newer and an OpenSSH client on the machine running Codex.
- An SSH server that you are allowed to use.
- The server host, account name, port, and a private key or another approved authentication method.
- A remote project directory, for example
~/workspace/demo. - A clear goal, such as “run the test suite”, “inspect the Vivado version”, or “upload this source file and build it”.
After installation, you can use the skill directly. If a required setting is missing, Codex will explain what is needed and ask before changing anything sensitive.
In a Codex conversation, ask:
Install the skill from https://github.com/Eriemon/remote-ssh.
After installation, start a new request by mentioning $erie-remote-ssh or by describing a task that explicitly needs SSH access. You should not copy private server lists, keys, or passwords into a public issue or document.
Use ordinary language. These examples show the amount of detail that helps:
$erie-remote-ssh Discover my configured SSH servers and show a redacted list.
$erie-remote-ssh Check the server named <server-name>, confirm that ~/workspace/demo is reachable, and report the Python and Vivado versions. Do not change files.
$erie-remote-ssh On <server-name>, upload <local-file> to build/input.cpp, show me the request and risks, then wait for my confirmation before running anything.
$erie-remote-ssh Run the project's approved test command in ~/workspace/demo. Keep the work inside that directory and give me the job id and log location if it takes a long time.
Replace angle-bracket values with your own configured server name, local file, and project details. If you do not know the server name, ask for discovery first.
- Discover — Codex reads the configured server facts and does not scan unknown hosts.
- Select — it resolves one server and checks the account, port, key, and effective remote workdir.
- Prepare — if a project directory or key reference is missing, it explains the guided setup and waits for your choice.
- Preview — for an upload, delete, directory change, or command, it shows the target, workdir, reason, payload, and risk categories before execution.
- Confirm — low-risk work can proceed after the agent's boundary review; high-risk or external side effects require the dedicated confirmation described in the preview.
- Deliver — it reports the outcome, exit status, logs, job id, and relevant output paths with sensitive values redacted.
| Request | What you see before execution | What happens next |
|---|---|---|
| Discover, check, list, or inspect | Selected target and read-only checks | Codex returns the facts without changing the server. |
| Upload or create a directory | Local source, remote relative path, effective workdir, reason, and risk | The exact request is reviewed before it runs. |
| Run a command | Command intent, target, workdir, and detected risk categories | The reviewed request is the only command that can execute. |
| Delete, change permissions, use a secret, or start background work | Extra warning and the specific side effect | Codex asks for the required confirmation or blocks the request. |
| Shutdown or reboot | A dedicated power-action confirmation phrase | Nothing runs without that exact confirmation. |
| Long-running build or test | Job purpose and the returned job id | Use status and log requests to inspect progress; an SSH timeout alone is not treated as a failed job. |
A normal result includes:
- the server and effective project workdir, with sensitive connection values redacted;
- the checks and actions that were actually performed;
- success, failure, or blocked status with an exit code when available;
- job id, log location, downloaded files, or generated artifacts when relevant;
- the reason a request was stopped, if a boundary or confirmation was missing;
- a concise next step when the task needs your decision.
The skill does not claim that a tool exists merely because it was requested. An inventory result such as not_detected means the configured probe did not find an executable; it is not proof that the software is absent.
| Boundary | User-facing behavior |
|---|---|
| Target selection | Only configured targets or explicitly shown OpenSSH aliases are used; there is no network scan. |
| Remote paths | Built-in file operations stay relative to the effective project workdir; absolute paths and parent traversal are rejected. |
| Local uploads | Upload sources must stay inside configured upload roots; sensitive locations require an explicit sensitive-upload confirmation. |
| SSH changes | Keys, known_hosts, SSH configuration, and remote authorized keys are never changed silently. |
| Commands | Requests are shown and reviewed before writes or arbitrary commands run. Catastrophic commands remain blocked. |
| Secrets and logs | Connection details are redacted by default, and audit records store command hashes rather than plaintext commands. |
Can I use an SSH alias instead of a server record? Yes, when discovery reports a usable OpenSSH alias. It is a temporary selection and is not written back as a new server record.
What if authentication fails? Ask Codex to inspect the key setup. It can guide a key-only repair and show the path and effect before any local key-generation or known_hosts change.
Can it work outside my project directory? Not through built-in file operations. Use a new reviewed request and an explicit project workdir instead of bypassing the boundary.
Can it run a long Vitis, Vivado, build, or test command? Yes, when the command is appropriate for the selected workdir and its review rules. Long work should use a tracked job so you can inspect status and logs.
Where is the detailed command reference? The installed skill's SKILL.md and references/ files contain the advanced request names and policy details. Most users only need the natural-language examples above.
Jiyuan Liu and He Li are with the School of Electronic Science and Engineering, Southeast University (东南大学). The work is developed with the Heterogeneous Intelligence and Quantum Computing Laboratory (HIQC).
If you build on this skill, cite it through CITATION.cff:
@software{liu_2026_remote_ssh,
author = {Jiyuan Liu and He Li},
title = {{RemoteSSH}: A Codex Skill for Governed SSH Workflows},
year = {2026},
version = {2.1.7},
date = {2026-08-11},
url = {https://github.com/Eriemon/remote-ssh},
license = {Apache-2.0}
}RemoteSSH is released under the Apache License 2.0. See LICENSE, SECURITY.md, and CITATION.cff.