Add simple SSH connection wizard

Author: MehediHossain95

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.5.0
+
+- Added `remote_connection_wizard`, a simple user-facing Add SSH Connection tool with only Name, SSH Host, SSH Port, and Identity File fields.
+- Added `codex-remote-ssh add` CLI fallback for users who need a terminal-based setup flow.
+- Added `codex-remote-ssh list` for inspecting saved connection profiles without secrets.
+
 ## 0.4.0
 
 - Added remote workspace bootstrap checks for OS, shell, user, workspace path, and common development tools.

plugins/remote-ssh/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-ssh",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Enterprise-grade Remote SSH tools for Codex with host policies, audit logging, and safe file operations.",
   "author": {
     "name": "Zain Technologies LTD",
@@ -22,7 +22,7 @@
   "interface": {
     "displayName": "Remote SSH",
     "shortDescription": "Enterprise Remote SSH operations for Codex",
-    "longDescription": "Remote SSH by Zain Technologies LTD connects Codex to trusted servers, devboxes, and private infrastructure through a local MCP bridge. It supports conversational connection setup, saved host aliases, remote workspace bootstrap checks, tree/search/git tools, path allowlists, write opt-in controls, blocked command policies, timeouts, output limits, and JSONL audit logs for professional remote development and operations workflows.",
+    "longDescription": "Remote SSH by Zain Technologies LTD connects Codex to trusted servers, devboxes, and private infrastructure through a local MCP bridge. It supports a simple Add SSH Connection wizard, conversational connection setup, saved host aliases, remote workspace bootstrap checks, tree/search/git tools, path allowlists, write opt-in controls, blocked command policies, timeouts, output limits, and JSONL audit logs for professional remote development and operations workflows.",
     "developerName": "Zain Technologies LTD",
     "category": "Development",
     "capabilities": [

plugins/remote-ssh/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.5.0
+
+- Added `remote_connection_wizard`, a simple user-facing Add SSH Connection tool with only Name, SSH Host, SSH Port, and Identity File fields.
+- Added `codex-remote-ssh add` CLI fallback for users who need a terminal-based setup flow.
+- Added `codex-remote-ssh list` for inspecting saved connection profiles without secrets.
+
 ## 0.4.0
 
 - Added remote workspace bootstrap checks for OS, shell, user, workspace path, and common development tools.

plugins/remote-ssh/CONFIGURATION.md

@@ -16,7 +16,7 @@ Advanced users can override this with `REMOTE_SSH_CONFIG_FILE` or provide epheme
 
 ## Automatic Connection Setup
 
-`remote_add_host` accepts the same fields users expect from a modern Remote SSH form:
+`remote_connection_wizard` accepts the same fields users expect from a modern Remote SSH form:
 
 | Form Field | Tool Field | Notes |
 | --- | --- | --- |
@@ -28,6 +28,14 @@ Advanced users can override this with `REMOTE_SSH_CONFIG_FILE` or provide epheme
 | Allowed Paths | `allowedPaths` | Optional safety policy for file tools. |
 | Allow Writes | `allowWrites` | Defaults to `false`. |
 
+Advanced users and admins can use `remote_add_host` for policy fields such as `workspaceRoot`, `allowedPaths`, and `allowWrites`.
+
+Terminal fallback:
+
+```bash
+codex-remote-ssh add
+```
+
 ## `REMOTE_SSH_HOSTS`
 
 Set this environment variable to a JSON object keyed by host alias.

plugins/remote-ssh/README.md

@@ -77,6 +77,21 @@ Most users should add connections conversationally:
 Add an SSH connection named hms for hmsadmin@192.168.128.7 using identity file ~/.ssh/id_ed25519_hms.
 ```
 
+If Codex renders the tool as a form, the normal setup only needs:
+
+```text
+Name
+SSH Host
+SSH Port
+Identity File (Private Key)
+```
+
+If the plugin UI is unavailable, use the terminal fallback:
+
+```bash
+codex-remote-ssh add
+```
+
 The plugin saves profiles to:
 
 ```text
@@ -127,6 +142,7 @@ Use Remote SSH to tail the last 100 lines of /var/log/nginx/error.log on hms.
 
 | Tool | Purpose |
 | --- | --- |
+| `remote_connection_wizard` | Adds a connection with the simple Name, SSH Host, SSH Port, Identity File form. |
 | `remote_add_host` | Saves or updates an SSH connection profile. |
 | `remote_remove_host` | Removes a saved SSH connection profile. |
 | `remote_test_connection` | Validates a saved SSH connection. |

plugins/remote-ssh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaintechnologiesltd/codex-remote-ssh",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Enterprise-grade Remote SSH MCP tools for OpenAI Codex.",
   "license": "MIT",
   "author": {
@@ -27,6 +27,7 @@
     "developer-tools"
   ],
   "bin": {
+    "codex-remote-ssh": "scripts/remote-ssh-cli.js",
     "codex-remote-ssh-mcp": "scripts/remote-ssh-mcp.js"
   },
   "files": [

plugins/remote-ssh/scripts/remote-ssh-cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+"use strict";
+
+const readline = require("node:readline/promises");
+const { stdin: input, stdout: output } = require("node:process");
+const {
+  cleanHostProfile,
+  readWritableConfig,
+  redactConfig,
+  writeWritableConfig,
+} = require("./remote-ssh-mcp.js");
+
+function usage() {
+  console.log(`Codex Remote SSH
+
+Usage:
+  codex-remote-ssh add
+  codex-remote-ssh list
+
+Commands:
+  add   Prompt for Name, SSH Host, SSH Port, and Identity File.
+  list  List saved SSH connection profiles without secrets.
+`);
+}
+
+async function addConnection() {
+  const rl = readline.createInterface({ input, output });
+  try {
+    const name = (await rl.question("Name: ")).trim();
+    const sshHost = (await rl.question("SSH Host (user@hostname or ~/.ssh/config host): ")).trim();
+    const portAnswer = (await rl.question("SSH Port [22]: ")).trim();
+    const identityFile = (await rl.question("Identity File (Private Key) [default SSH key]: ")).trim();
+
+    if (!name || !sshHost) {
+      throw new Error("Name and SSH Host are required.");
+    }
+
+    const { file, config } = readWritableConfig();
+    config.hosts[name] = cleanHostProfile({
+      name,
+      sshHost,
+      port: portAnswer ? Number(portAnswer) : 22,
+      identityFile: identityFile || undefined,
+      overwrite: true,
+    });
+    writeWritableConfig(file, config);
+
+    console.log(`Saved ${name} to ${file}`);
+  } finally {
+    rl.close();
+  }
+}
+
+function listConnections() {
+  const { file, config } = readWritableConfig();
+  console.log(`Config: ${file}`);
+  console.log(JSON.stringify(
+    Object.fromEntries(
+      Object.entries(config.hosts).map(([name, profile]) => [name, redactConfig({ alias: name, ...profile })]),
+    ),
+    null,
+    2,
+  ));
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (command === "add") {
+    await addConnection();
+    return;
+  }
+  if (command === "list") {
+    listConnections();
+    return;
+  }
+  usage();
+  process.exitCode = command ? 1 : 0;
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
+

plugins/remote-ssh/scripts/remote-ssh-mcp.js

@@ -7,7 +7,7 @@ const os = require("node:os");
 const path = require("node:path");
 const readline = require("node:readline");
 
-const SERVER_VERSION = "0.4.0";
+const SERVER_VERSION = "0.5.0";
 const PROTOCOL_VERSION = "2024-11-05";
 const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
 const DEFAULT_CONNECT_TIMEOUT_SECONDS = 15;
@@ -354,6 +354,42 @@ function textResult(payload) {
 }
 
 const tools = [
+  {
+    name: "remote_connection_wizard",
+    description: "Add SSH connection using the simple user-facing form: Name, SSH Host, SSH Port, and Identity File.",
+    inputSchema: {
+      type: "object",
+      title: "Add SSH connection",
+      description: "Connect to a remote machine for Codex remote work.",
+      properties: {
+        name: {
+          type: "string",
+          title: "Name",
+          description: "A friendly name for this SSH connection, such as My Server.",
+        },
+        sshHost: {
+          type: "string",
+          title: "SSH Host",
+          description: "user@myserver.com or a host from ~/.ssh/config.",
+        },
+        port: {
+          type: "integer",
+          title: "SSH Port",
+          description: "Leave empty to use default 22 or SSH config.",
+          minimum: 1,
+          maximum: 65535,
+          default: 22,
+        },
+        identityFile: {
+          type: "string",
+          title: "Identity File (Private Key)",
+          description: "Leave empty to use default SSH key or SSH config. Example: ~/.ssh/id_rsa.",
+        },
+      },
+      required: ["name", "sshHost"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "remote_add_host",
     description: "Add or update a saved SSH connection profile in the Remote SSH config file.",
@@ -575,7 +611,7 @@ const tools = [
 ];
 
 async function callTool(name, args) {
-  if (name === "remote_add_host") {
+  if (name === "remote_connection_wizard" || name === "remote_add_host") {
     const alias = String(args.name || "").trim();
     if (!alias || !/^[A-Za-z0-9_.-]+$/.test(alias)) {
       throw new Error("Connection name must contain only letters, numbers, dots, underscores, or hyphens.");
@@ -788,8 +824,11 @@ module.exports = {
   handle,
   loadHostConfig,
   normalizeRemotePath,
+  readWritableConfig,
+  redactConfig,
   resolveRemoteWorkspacePath,
   shellQuote,
   startServer,
   tools,
+  writeWritableConfig,
 };

plugins/remote-ssh/skills/remote-ssh/SKILL.md

@@ -17,7 +17,8 @@ Use this skill when the user asks Codex to inspect or operate a configured remot
    - optional identity file
    - optional workspace root
    - optional allowed remote paths
-   Then use `remote_add_host` and test with `remote_test_connection`.
+   Then use `remote_connection_wizard` and test with `remote_test_connection`.
+   Use `remote_add_host` only when the user asks for advanced policy fields such as workspace root, allowed paths, or write access.
 3. When the user wants to work in a remote project, prefer workspace tools:
    - use `remote_workspace_bootstrap` to check environment readiness
    - use `remote_tree` to inspect project structure

plugins/remote-ssh/test/remote-ssh-mcp.test.js

@@ -34,6 +34,7 @@ assert.throws(() => assertCommandAllowed(config, "cat /etc/passwd"), /allowlist/
 assert.throws(() => assertCommandAllowed({ ...config, allowedCommands: [] }, "rm -rf /srv/app"), /policy/);
 
 assert.ok(tools.some((tool) => tool.name === "remote_hosts"));
+assert.ok(tools.some((tool) => tool.name === "remote_connection_wizard"));
 assert.ok(tools.some((tool) => tool.name === "remote_add_host"));
 assert.ok(tools.some((tool) => tool.name === "remote_remove_host"));
 assert.ok(tools.some((tool) => tool.name === "remote_test_connection"));
@@ -87,6 +88,6 @@ assert.deepEqual(
 assert.equal(base64Text("hello"), "aGVsbG8=");
 
 handle({ jsonrpc: "2.0", id: 1, method: "tools/list" }).then((response) => {
-  assert.ok(response.tools.length >= 15);
+  assert.ok(response.tools.length >= 16);
   console.log("remote-ssh-mcp tests passed");
 });