@pixlcore/xyplug-ssh 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PixlCore LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+<p align="center"><img src="https://raw.githubusercontent.com/pixlcore/xyplug-ssh/refs/heads/main/logo.png" height="160" alt="Remote SSH"/></p>
+<h1 align="center">Remote SSH</h1>
+
+A remote SSH event plugin for the [xyOps Workflow Automation System](https://xyops.io).  It connects to a remote host over SSH, and then runs either:
+
+- A remote command that receives a script on STDIN
+- A remote command that receives the full xyOps job JSON on STDIN
+
+This makes it useful both as a simple remote shell runner and as a transport layer for your own remote XYWP-aware workers.
+
+## Features
+
+- Pure Node.js / `npx` plugin.
+- No local `ssh` CLI required.
+- Supports private key, passphrase, password, or local `ssh-agent`
+- Optional host key fingerprint pinning
+- Preserves remote XYWP output when the remote command emits `{"xy":1,...}` lines
+
+## Requirements
+
+- `npx`
+- Network access from the xyOps runner host to the remote SSH server
+- A POSIX-like remote host with `/bin/sh`
+- `base64` or `openssl` available on the remote host for env var bootstrapping
+- Whatever remote runtime your command needs, e.g. `bash`, `python`, `node`, etc.
+
+## Secrets / Environment Variables
+
+The plugin looks up SSH auth from environment variables or [xyOps Secrets](https://docs.xyops.io/secrets) using these fixed names:
+
+- `SSH_PRIVATE_KEY`
+- `SSH_PASSPHRASE`
+- `SSH_PASSWORD`
+
+Put those in your xyOps Secret Vault when needed.
+
+Note that any secret variables that begin with `SSH_` are **not** forwarded to the remote server, by design.  Any *other* assigned xyOps secret variables are forwarded to the remote process environment.
+
+The plugin also exports a few helper variables remotely:
+
+- `XYOPS_JOB_ID`
+- `XYOPS_EVENT_ID`
+- `XYOPS_PLUGIN_ID`
+- `XYOPS_SERVER_ID`
+- `XYOPS_BASE_URL`
+- `XYOPS_RUN_MODE`
+
+## Plugin Parameters
+
+- `SSH Hostname`: Hostname or IP address
+- `Username`: SSH username
+- `Port`: SSH port
+- `Host Fingerprint`: Optional host key pin, recommended for production
+- `Connect Timeout`: SSH connect timeout in seconds
+- `Remote Env`: Extra key/value pairs to pass to the remote side
+- `Verbose Logging`: Adds connection/debug details to the job log
+
+## Run Modes
+
+### 1. Pipe Script to STDIN
+
+Use this when the remote command is something like `bash -se`, `python -`, or another interpreter that reads source code from STDIN.
+
+Typical example:
+
+- Remote Command: `bash -se`
+- Script Source: your shell script
+
+The plugin exports env vars first, then executes the remote command, then pipes your script into its STDIN.
+
+### 2. Pipe Full Job JSON
+
+Use this when the remote command is your own program that expects the full xyOps job payload on STDIN.
+
+Typical example:
+
+- Remote Command: `node /path/to/my-remote-plugin.js`
+
+If the remote program emits XYWP lines such as `{"xy":1,"progress":0.5}` or `{"xy":1,"code":0}`, the plugin passes them straight back to xyOps.
+
+If the remote program does not emit a final XYWP completion message, the plugin falls back to the SSH exit code.
+
+## Local Testing
+
+Install dependencies first:
+
+```bash
+npm install
+```
+
+Then pipe a sample job JSON into the plugin.
+
+### Script Mode Example
+
+```bash
+cat <<'JSON' | node index.js
+{
+  "xy": 1,
+  "type": "event",
+  "id": "jtestssh001",
+  "event": "etestssh001",
+  "plugin": "ptestssh001",
+  "server": "local",
+  "base_url": "https://xyops.example.com",
+  "params": {
+    "hostname": "127.0.0.1",
+    "username": "deploy",
+    "port": 22,
+    "connect_timeout_sec": 10,
+    "remote_env": {
+      "APP_ENV": "dev"
+    },
+    "tool": "script",
+    "remote_command": "bash -se",
+    "script": "set -euo pipefail\\necho \\\"remote host: $(hostname)\\\"\\necho \\\"job id: $XYOPS_JOB_ID\\\"\\n"
+  },
+  "secrets": {
+    "SSH_PRIVATE_KEY": "-----BEGIN OPENSSH PRIVATE KEY-----\\nREPLACE_ME\\n-----END OPENSSH PRIVATE KEY-----"
+  }
+}
+JSON
+```
+
+### Job JSON Mode Example
+
+```bash
+cat <<'JSON' | node index.js
+{
+  "xy": 1,
+  "type": "event",
+  "id": "jtestssh002",
+  "event": "etestssh002",
+  "plugin": "ptestssh002",
+  "server": "local",
+  "base_url": "https://xyops.example.com",
+  "params": {
+    "hostname": "127.0.0.1",
+    "username": "deploy",
+    "port": 22,
+    "tool": "job_json",
+    "remote_command": "node /opt/xyops/remote-plugin.js"
+  },
+  "secrets": {
+    "SSH_PRIVATE_KEY": "-----BEGIN OPENSSH PRIVATE KEY-----\\nREPLACE_ME\\n-----END OPENSSH PRIVATE KEY-----"
+  }
+}
+JSON
+```
+
+## Security Notes
+
+- Prefer private key auth stored in xyOps Secrets over inline passwords.
+- Set `Host Fingerprint` in production so the plugin pins the remote host key.
+
+## Data Collection
+
+This plugin does not intentionally collect telemetry, analytics, or usage metrics.
+
+## License
+
+MIT.

package/index.js

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+
+// SSH Plugin for xyOps
+// Copyright (c) 2026 PixlCore LLC
+// MIT License
+
+const { createHash } = require('crypto');
+const { Client } = require('ssh2');
+
+class HandledError extends Error {}
+
+const app = {
+	conn: null,
+	stream: null,
+	finalSent: false,
+	remoteSentFinal: false,
+	shuttingDown: false,
+	stdoutBuffer: '',
+	verbose: false,
+	exitCode: 0,
+	exitSignal: '',
+	
+	async run() {
+		const { raw, job } = await readJob();
+		this.rawJob = raw;
+		this.job = job;
+		this.params = job.params || {};
+		this.verbose = toBool(this.params.verbose);
+		
+		const mode = String(this.params.tool || 'script').trim() || 'script';
+		if (!TOOLS[mode]) fatal('params', `Unknown run mode: ${mode}`);
+		
+		const secrets = collectSecrets(job);
+		const target = parseTarget(
+			String(this.params.hostname || '').trim(),
+			String(this.params.username || '').trim(),
+			this.params.port
+		);
+		const auth = resolveAuth(secrets);
+		const remoteCommand = String(this.params.remote_command || '').trim();
+		if (!remoteCommand) fatal('params', "Required parameter 'remote_command' was not provided.");
+		
+		const connectTimeoutSec = toPositiveInt(this.params.connect_timeout_sec, 30);
+		const remoteEnv = buildRemoteEnv(job, this.params, secrets, mode);
+		const bootstrap = buildBootstrap(remoteEnv, remoteCommand);
+		const sshConfig = buildSshConfig(target, auth, this.params.host_fingerprint, connectTimeoutSec);
+		
+		this.installSignalHandlers();
+		this.log(`Connecting to ${target.username}@${target.host}:${target.port} (${mode})`);
+		this.log(`Remote command: ${remoteCommand}`);
+		
+		await this.connect(sshConfig);
+		await this.exec(bootstrap);
+		
+		const payload = (mode === 'job_json')
+			? ensureTrailingNewline(this.rawJob)
+			: ensureTrailingNewline(String(this.params.script || ''));
+		
+		if ((mode === 'script') && !payload.trim()) {
+			fatal('params', "Required parameter 'script' was not provided.");
+		}
+		
+		this.stream.end(payload);
+	},
+	
+	connect(config) {
+		return new Promise((resolve, reject) => {
+			const conn = new Client();
+			this.conn = conn;
+			
+			conn.once('ready', () => {
+				conn.on('error', (err) => {
+					if (this.shuttingDown || this.finalSent) return;
+					this.fail('ssh', err && err.message ? err.message : 'SSH connection error.');
+				});
+				resolve();
+			});
+			conn.once('error', reject);
+			
+			conn.connect(config);
+		});
+	},
+	
+	exec(bootstrap) {
+		return new Promise((resolve, reject) => {
+			const command = `/bin/sh -lc ${quoteShell(bootstrap)}`;
+			this.conn.exec(command, (err, stream) => {
+				if (err) return reject(err);
+				this.stream = stream;
+				
+				stream.on('data', (chunk) => this.handleStdout(chunk));
+				stream.stderr.on('data', (chunk) => process.stderr.write(chunk));
+				stream.on('exit', (code, signal) => {
+					this.exitCode = (typeof code === 'number') ? code : 0;
+					this.exitSignal = signal || '';
+				});
+				stream.on('close', () => this.handleClose());
+				
+				resolve(stream);
+			});
+		});
+	},
+	
+	handleStdout(chunk) {
+		const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+		process.stdout.write(text);
+		this.stdoutBuffer += text;
+		
+		let idx = 0;
+		while ((idx = this.stdoutBuffer.indexOf('\n')) > -1) {
+			const line = this.stdoutBuffer.slice(0, idx).replace(/\r$/, '');
+			this.stdoutBuffer = this.stdoutBuffer.slice(idx + 1);
+			this.inspectLine(line);
+		}
+	},
+	
+	inspectLine(line) {
+		if (!line || !line.trim()) return;
+		try {
+			const msg = JSON.parse(line);
+			if (msg && (msg.xy === 1) && Object.prototype.hasOwnProperty.call(msg, 'code')) {
+				this.remoteSentFinal = true;
+			}
+		}
+		catch (err) {
+			// ignore plain text output
+		}
+	},
+	
+	handleClose() {
+		if (this.stdoutBuffer) {
+			this.inspectLine(this.stdoutBuffer.replace(/\r$/, ''));
+			this.stdoutBuffer = '';
+		}
+		
+		if (this.conn) {
+			try { this.conn.end(); }
+			catch (err) {;}
+		}
+		
+		if (this.shuttingDown || this.finalSent) return process.exit(0);
+		if (this.remoteSentFinal) return process.exit(0);
+		
+		if (this.exitSignal) {
+			return this.sendFinal({
+				code: `signal:${this.exitSignal}`,
+				description: `Remote command exited due to signal ${this.exitSignal}.`
+			});
+		}
+		
+		if (this.exitCode) {
+			return this.sendFinal({
+				code: this.exitCode,
+				description: `Remote command exited with code ${this.exitCode}.`
+			});
+		}
+		
+		return this.sendFinal({ code: 0 });
+	},
+	
+	sendFinal(payload) {
+		if (this.finalSent) return;
+		this.finalSent = true;
+		payload.xy = 1;
+		process.stdout.write(`${JSON.stringify(payload)}\n`, () => process.exit(0));
+	},
+	
+	fail(code, description) {
+		this.sendFinal({ code, description });
+	},
+	
+	log(message) {
+		if (this.verbose) process.stderr.write(`[xyplug-ssh] ${message}\n`);
+	},
+	
+	installSignalHandlers() {
+		const handler = (signal) => {
+			this.shuttingDown = true;
+			this.log(`Caught ${signal}, closing SSH session.`);
+			try {
+				if (this.stream) this.stream.close();
+			}
+			catch (err) {;}
+			try {
+				if (this.conn) this.conn.end();
+			}
+			catch (err) {;}
+			setTimeout(() => process.exit(0), 250).unref();
+		};
+		
+		process.once('SIGTERM', () => handler('SIGTERM'));
+		process.once('SIGINT', () => handler('SIGINT'));
+	}
+};
+
+const TOOLS = {
+	script: true,
+	job_json: true
+};
+
+async function readJob() {
+	const chunks = [];
+	for await (const chunk of process.stdin) {
+		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	}
+	
+	const raw = Buffer.concat(chunks).toString('utf8').trim();
+	if (!raw) fatal('input', 'No JSON input received on STDIN.');
+	
+	try {
+		return { raw, job: JSON.parse(raw) };
+	}
+	catch (err) {
+		fatal('input', `Failed to parse JSON input: ${err.message}`);
+	}
+}
+
+function parseTarget(hostname, username, portFallback) {
+	const host = String(hostname || '').trim();
+	const user = String(username || '').trim();
+	const port = toPositiveInt(portFallback, 22);
+	
+	if (!host) fatal('params', "Required parameter 'hostname' was not provided.");
+	if (!user) fatal('params', "Required parameter 'username' was not provided.");
+	
+	return { host, port, username: user };
+}
+
+function resolveAuth(secrets) {
+	const privateKey = resolveNamedValue('SSH_PRIVATE_KEY', secrets);
+	const passphrase = resolveNamedValue('SSH_PASSPHRASE', secrets);
+	const password = resolveNamedValue('SSH_PASSWORD', secrets);
+	const agent = process.env.SSH_AUTH_SOCK || '';
+	
+	if (!privateKey && !password && !agent) {
+		fatal(
+			'auth',
+			'No SSH auth credentials were found. Set SSH_PRIVATE_KEY, SSH_PASSWORD, or provide an ssh-agent via SSH_AUTH_SOCK.'
+		);
+	}
+	
+	return { privateKey, passphrase, password, agent };
+}
+
+function resolveNamedValue(name, secrets) {
+	if (!name) return '';
+	if (Object.prototype.hasOwnProperty.call(secrets, name)) return String(secrets[name]);
+	if (Object.prototype.hasOwnProperty.call(process.env, name)) return String(process.env[name]);
+	return '';
+}
+
+function buildSshConfig(target, auth, fingerprint, connectTimeoutSec) {
+	const config = {
+		host: target.host,
+		port: target.port,
+		username: target.username,
+		readyTimeout: connectTimeoutSec * 1000,
+		keepaliveInterval: 15000,
+		keepaliveCountMax: 4
+	};
+	
+	if (auth.privateKey) config.privateKey = Buffer.from(auth.privateKey, 'utf8');
+	if (auth.passphrase) config.passphrase = auth.passphrase;
+	if (auth.password) config.password = auth.password;
+	if (!auth.privateKey && !auth.password && auth.agent) config.agent = auth.agent;
+	
+	const expected = String(fingerprint || '').trim();
+	if (expected) {
+		config.hostVerifier = function(hostKey) {
+			const actualSha256 = `SHA256:${createHash('sha256').update(hostKey).digest('base64').replace(/=+$/, '')}`;
+			const actualMd5 = createHash('md5').update(hostKey).digest('hex').match(/.{2}/g).join(':');
+			return matchesFingerprint(expected, actualSha256, actualMd5);
+		};
+	}
+	
+	return config;
+}
+
+function matchesFingerprint(expected, actualSha256, actualMd5) {
+	const value = String(expected || '').trim();
+	if (!value) return true;
+	if (/^sha256:/i.test(value)) return value === actualSha256;
+	if (/^[a-f0-9]{2}(?::[a-f0-9]{2}){15}$/i.test(value)) return value.toLowerCase() === actualMd5.toLowerCase();
+	return (`SHA256:${value.replace(/^SHA256:/i, '').replace(/=+$/, '')}` === actualSha256);
+}
+
+function collectSecrets(job) {
+	const secrets = {};
+	if (!job || !job.secrets || (typeof job.secrets !== 'object') || Array.isArray(job.secrets)) return secrets;
+	
+	for (const [key, value] of Object.entries(job.secrets)) {
+		if (!isValidEnvName(key) || (value === undefined) || (value === null)) continue;
+		secrets[key] = String(value);
+	}
+	
+	return secrets;
+}
+
+function buildRemoteEnv(job, params, secrets, mode) {
+	const env = {};
+	
+	for (const [key, value] of Object.entries(secrets)) {
+		if (!/^(SSH_)/.test(key)) continue;
+		env[key] = value;
+	}
+	
+	for (const [key, value] of Object.entries(process.env)) {
+		if (!/^(XYOPS_|JOB_)/.test(key)) continue;
+		if (!isValidEnvName(key)) continue;
+		if (value === undefined || value === null) continue;
+		env[key] = String(value);
+	}
+	
+	const meta = {
+		XYOPS_JOB_ID: job.id || '',
+		XYOPS_EVENT_ID: job.event || '',
+		XYOPS_PLUGIN_ID: job.plugin || '',
+		XYOPS_SERVER_ID: job.server || '',
+		XYOPS_BASE_URL: job.base_url || '',
+		XYOPS_RUN_MODE: mode
+	};
+	
+	for (const [key, value] of Object.entries(meta)) {
+		if (value !== undefined && value !== null && value !== '') env[key] = String(value);
+	}
+	
+	for (const [key, value] of Object.entries(params)) {
+		if (KNOWN_PARAM_KEYS.has(key)) continue;
+		if (!isValidEnvName(key)) continue;
+		if ((typeof value === 'string') || (typeof value === 'number')) {
+			env[key] = String(value);
+		}
+	}
+	
+	const extra = params.remote_env;
+	if (extra !== undefined && extra !== null) {
+		if ((typeof extra !== 'object') || Array.isArray(extra)) {
+			fatal('params', "Parameter 'remote_env' must be a JSON object.");
+		}
+		
+		for (const [key, value] of Object.entries(extra)) {
+			if (!isValidEnvName(key)) fatal('params', `Invalid remote_env key: ${key}`);
+			env[key] = normalizeEnvValue(value);
+		}
+	}
+	
+	return env;
+}
+
+function normalizeEnvValue(value) {
+	if (value === undefined || value === null) return '';
+	if (typeof value === 'string') return value;
+	if ((typeof value === 'number') || (typeof value === 'boolean')) return String(value);
+	return JSON.stringify(value);
+}
+
+function buildBootstrap(env, remoteCommand) {
+	const lines = [
+		'decode_b64() {',
+		'  if command -v base64 >/dev/null 2>&1; then',
+		'    base64 --decode 2>/dev/null || base64 -d 2>/dev/null || base64 -D 2>/dev/null;',
+		'  elif command -v openssl >/dev/null 2>&1; then',
+		'    openssl base64 -d -A;',
+		'  else',
+		'    echo "Missing base64 or openssl on remote host." >&2;',
+		'    return 127;',
+		'  fi',
+		'}'
+	];
+	
+	for (const key of Object.keys(env).sort()) {
+		const encoded = Buffer.from(String(env[key]), 'utf8').toString('base64');
+		lines.push(`export ${key}="$(printf %s ${quoteShell(encoded)} | decode_b64)"`);
+	}
+	
+	lines.push(`exec ${remoteCommand}`);
+	return lines.join('\n');
+}
+
+function isValidEnvName(name) {
+	return /^[A-Za-z_][A-Za-z0-9_]*$/.test(String(name || ''));
+}
+
+function toBool(value) {
+	if ((value === true) || (value === false)) return value;
+	const text = String(value || '').trim().toLowerCase();
+	return (text === '1') || (text === 'true') || (text === 'yes') || (text === 'on');
+}
+
+function toPositiveInt(value, fallback) {
+	const num = parseInt(value, 10);
+	return Number.isFinite(num) && (num > 0) ? num : fallback;
+}
+
+function ensureTrailingNewline(text) {
+	const value = String(text || '');
+	return value.endsWith('\n') ? value : `${value}\n`;
+}
+
+function quoteShell(text) {
+	return `'${String(text).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+const KNOWN_PARAM_KEYS = new Set([
+	'hostname',
+	'username',
+	'port',
+	'host_fingerprint',
+	'connect_timeout_sec',
+	'remote_env',
+	'verbose',
+	'tool',
+	'remote_command',
+	'script'
+]);
+
+function fatal(code, description) {
+	app.fail(code, description);
+	throw new HandledError(description);
+}
+
+app.run().catch((err) => {
+	if (err instanceof HandledError) return;
+	if (app.verbose && err) {
+		process.stderr.write(`${err && err.stack ? err.stack : err}\n`);
+	}
+	app.fail('error', err && err.message ? err.message : 'Unknown error');
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "@pixlcore/xyplug-ssh",
+	"version": "1.0.0",
+	"description": "An SSH runner plugin for the xyOps workflow automation system.",
+	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
+	"homepage": "https://github.com/pixlcore/xyplug-ssh",
+	"license": "MIT",
+	"bin": {
+		"xyplug-ssh": "index.js"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/pixlcore/xyplug-ssh"
+	},
+	"bugs": {
+		"url": "https://github.com/pixlcore/xyplug-ssh/issues"
+	},
+	"keywords": [
+		"xyops",
+		"ssh",
+		"runner",
+		"remote"
+	],
+	"files": [
+		"index.js",
+		"README.md",
+		"LICENSE.md",
+		"xyops.json"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"dependencies": {
+		"ssh2": "^1.16.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/xyops.json

@@ -0,0 +1,125 @@
+{
+	"type": "xypdf",
+	"description": "xyOps Portable Data Object",
+	"version": "1.0",
+	"items": [
+		{
+			"type": "plugin",
+			"data": {
+				"id": "pmsshnak612ag9veb",
+				"title": "Remote SSH",
+				"enabled": true,
+				"type": "event",
+				"command": "npx -y @pixlcore/xyplug-ssh@1.0.0",
+				"script": "",
+				"kill": "parent",
+				"runner": true,
+				"notes": "Run remote commands or scripts over SSH.",
+				"icon": "console-network-outline",
+				"params": [
+					{
+						"id": "hostname",
+						"title": "SSH Hostname",
+						"type": "text",
+						"value": "",
+						"caption": "Remote hostname or IP address, e.g. `deploy.example.com` or `10.0.0.25`.",
+						"required": true
+					},
+					{
+						"id": "username",
+						"title": "Username",
+						"type": "text",
+						"value": "",
+						"caption": "SSH username to connect with.",
+						"required": true
+					},
+					{
+						"id": "port",
+						"title": "Port",
+						"type": "text",
+						"variant": "number",
+						"value": 22,
+						"caption": "SSH TCP port."
+					},
+					{
+						"id": "host_fingerprint",
+						"title": "Host Fingerprint",
+						"type": "text",
+						"value": "",
+						"caption": "Optional host key pin. Accepts `SHA256:...` or MD5 fingerprint text. Recommended for production."
+					},
+					{
+						"id": "connect_timeout_sec",
+						"title": "Connect Timeout (sec)",
+						"type": "text",
+						"variant": "number",
+						"value": 30,
+						"caption": "How long to wait for the SSH session to connect."
+					},
+					{
+						"id": "remote_env",
+						"title": "Remote Env",
+						"type": "json",
+						"value": {},
+						"caption": "Optional extra key/value pairs to send to the remote side."
+					},
+					{
+						"id": "verbose",
+						"title": "Verbose Logging",
+						"type": "checkbox",
+						"value": false,
+						"caption": "Log SSH connection details to the job log."
+					},
+					{
+						"id": "tool",
+						"title": "Run Mode",
+						"type": "toolset",
+						"caption": "",
+						"data": {
+							"tools": [
+								{
+									"id": "script",
+									"title": "Pipe Script to STDIN",
+									"description": "Export env vars remotely and pipe your script into the selected command.",
+									"fields": [
+										{
+											"id": "remote_command",
+											"title": "Remote Command",
+											"type": "text",
+											"value": "bash -se",
+											"caption": "Command to execute remotely. It will receive the script on STDIN.",
+											"required": true
+										},
+										{
+											"id": "script",
+											"title": "Script Source",
+											"type": "code",
+											"value": "#!/usr/bin/env bash\nset -euo pipefail\n\necho \"Hello from $(hostname)\"\n",
+											"caption": "Script contents to pipe into the remote command.",
+											"required": true
+										}
+									]
+								},
+								{
+									"id": "job_json",
+									"title": "Pipe Full Job JSON",
+									"description": "Send the full xyOps job JSON to a remote program that knows how to read STDIN and optionally emit XYWP.",
+									"fields": [
+										{
+											"id": "remote_command",
+											"title": "Remote Command",
+											"type": "text",
+											"value": "node /path/to/my-remote-plugin.js",
+											"caption": "Command to execute remotely. It will receive the full job JSON on STDIN.",
+											"required": true
+										}
+									]
+								}
+							]
+						}
+					}
+				]
+			}
+		}
+	]
+}