Plugins

Extend xyOps with custom plugins in any programming language

Plugins let you extend xyOps functionality by writing code in any language. xyOps ships with several built-in plugins for common tasks, and you can write your own or discover community plugins in the Marketplace.

Plugin types

xyOps supports two main plugin types:

Event plugins

Execute job logic on target servers—the primary plugin type

Monitor plugins

Collect custom metrics for monitoring and alerting

Event plugins

Event plugins are the main type of plugin in xyOps. They execute the code that runs your jobs. When events launch a job (standalone or as part of a workflow), they invoke an event plugin on the target server.

Built-in event plugins

xyOps ships with these event plugins:

Plugin	Description
Shell Plugin	Execute arbitrary shell scripts without learning the plugin API
HTTP Request Plugin	Send HTTP requests with custom headers, body, and methods
Test Plugin	Output sample data and files for testing workflows
Docker Plugin	Run scripts inside Docker containers

Plugin communication

Event plugins communicate with xyOps using JSON over STDIN/STDOUT. This is called the xyOps Wire Protocol.

• Input: JSON document on STDIN with job details, parameters, and input files
• Output: JSON lines on STDOUT to report progress, status, and completion

The wire protocol is language-agnostic—write plugins in Node.js, Python, Go, Rust, or any language that can read/write JSON.

Job input

When your plugin is invoked, it receives a JSON document on STDIN with these properties:

xy · number · required

Wire protocol version (always 1)

type · string · required

Plugin type (event or monitor)

params · object

Plugin parameter values configured in the event

input · object

Input data and files from previous workflow nodes

Show properties

data · object

JSON data from previous job

files · array

Array of file metadata objects with id, filename, size, date

cwd · string

Current working directory (unique temp directory for this job)

event · string

Event ID that launched this job

id · string

Unique job ID

Example input from ~/workspace/source/docs/plugins.md:44-92:

{
  "xy": 1,
  "type": "event",
  "targets": ["main"],
  "params": {
    "animal": "frog",
    "color": "green"
  },
  "input": {
    "data": { "foo": "bar" },
    "files": []
  },
  "event": "emi11ejdlde",
  "id": "jmi11fqevei",
  "state": "active",
  "started": 1763256572.033,
  "cwd": "/opt/xyops/satellite/temp/jobs/jmi11fqevei",
  "log_file": "/opt/xyops/satellite/logs/jobs/job-jmi11fqevei.log"
}

Input files

Input files are automatically downloaded to your job’s temp directory. Access them through:

1. File listing: Check input.files array for metadata
2. Direct access: Files are written to the current working directory

"input": {
  "data": {},
  "files": [
    {
      "id": "fmktcdzp1skybhk9",
      "date": 1769321584,
      "filename": "mario.mp3",
      "size": 309425,
      "username": "admin"
    }
  ]
}

Job output

Your plugin writes JSON to STDOUT to report status. All JSON must be compacted to a single line ending with \n.

Success completion

{ "xy": 1, "code": 0 }

Error completion

{ "xy": 1, "code": 1, "description": "Failed to connect to database" }

Once you send a JSON line with a code property, xyOps considers the job complete. Make this your last JSON output.

Progress updates

Report progress while your job runs:

{ "xy": 1, "progress": 0.5 }

Progress is a float between 0.0 (0%) and 1.0 (100%).

Status messages

Set a status string displayed during job execution:

{ "xy": 1, "status": "Processing file 34 of 68..." }

Combine progress and status:

{ "xy": 1, "progress": 0.5, "status": "Processing client report..." }

Performance metrics

Report how your plugin spent time during execution:

{ "xy": 1, "perf": { "db": 18.51, "http": 3.22, "gzip": 0.84 } }

Metrics are in seconds by default. For milliseconds, include scale:

{ "xy": 1, "perf": { "scale": 1000, "db": 1851, "http": 3220 } }

Output data and files

Pass structured data to downstream workflow nodes:

{ "xy": 1, "data": { "result": "success", "count": 42 } }

Pass file paths to downstream nodes:

{ "xy": 1, "files": ["output.json", "report.pdf"] }

File paths are relative to the job’s temp directory. xyOps uploads them automatically.

Plugin parameters

Define user-configurable parameters in your plugin definition:

"params": [
  {
    "id": "api_key",
    "title": "API Key",
    "type": "text",
    "required": true
  },
  {
    "id": "endpoint",
    "title": "Endpoint URL",
    "type": "text",
    "value": "https://api.example.com"
  },
  {
    "id": "script",
    "title": "Script Code",
    "type": "code",
    "syntax": "python"
  }
]

Parameter types include:

• text - Single-line text input
• textarea - Multi-line text input
• code - Code editor with syntax highlighting
• select - Dropdown menu
• checkbox - Boolean toggle
• hidden - Hidden field for internal values

Parameters are passed to your plugin in the params object and as environment variables.

Monitor plugins

Monitor plugins collect custom metrics on a schedule. They run on target servers and report numeric values back to xyOps for graphing and alerting.

Monitor plugin input

{
  "xy": 1,
  "type": "monitor",
  "params": {
    "database": "mydb",
    "query": "SELECT COUNT(*) FROM users"
  }
}

Monitor plugin output

Return a numeric value:

{ "xy": 1, "value": 42.5 }

For errors:

{ "xy": 1, "error": "Failed to connect to database" }

Plugin examples

Shell plugin example

The simplest plugin type. Just write shell code:

#!/bin/bash
echo "Starting backup..."
tar -czf backup.tar.gz /data
echo '{"xy":1,"code":0,"files":["backup.tar.gz"]}'

No wire protocol needed for basic shell scripts.

Python plugin with progress

#!/usr/bin/env python3
import sys
import json
import time

# Read input
input_data = json.loads(sys.stdin.read())
total = input_data['params']['count']

# Process with progress
for i in range(total):
    progress = (i + 1) / total
    sys.stdout.write(json.dumps({"xy": 1, "progress": progress}) + "\n")
    sys.stdout.flush()
    time.sleep(0.1)

# Complete
sys.stdout.write(json.dumps({"xy": 1, "code": 0}) + "\n")

Node.js plugin with files

#!/usr/bin/env node
const fs = require('fs');
const readline = require('readline');

// Read input from STDIN
let input = '';
const rl = readline.createInterface({
  input: process.stdin,
  terminal: false
});

rl.on('line', (line) => { input += line; });
rl.on('close', () => {
  const data = JSON.parse(input);
  
  // Process input files
  const files = data.input.files;
  console.log(JSON.stringify({ xy: 1, status: `Processing ${files.length} files` }));
  
  // Create output file
  fs.writeFileSync('result.json', JSON.stringify({ result: 'done' }));
  
  // Report completion
  console.log(JSON.stringify({ xy: 1, code: 0, files: ['result.json'] }));
});

Creating custom plugins

1. Choose your language

   Pick any language that can read STDIN and write to STDOUT. Popular choices: Node.js, Python, Go, Rust, Bash.

2. Implement the wire protocol

   Read JSON from STDIN on startup. Write JSON lines to STDOUT for updates and completion.

   Test your plugin locally by piping JSON to it: echo '{"xy":1,"type":"event"}' | ./your-plugin.sh

3. Define plugin metadata

   Create your plugin definition in xyOps with:

   • Title and description
   • Command to execute (shell command, Docker run, npx, etc.)
   • Parameters users can configure
   • Icon from Material Design Icons
4. Test with a job

   Create a test event using your plugin. Run it manually and check the job log for proper JSON output.

Publishing to the marketplace

Once your plugin is working, share it with the community:

1. Host your code on GitHub with an OSI-approved license
2. Add plugin metadata to your repository
3. Submit to the Marketplace

See Marketplace for full publishing requirements.

Best practices

Flush output

Disable output buffering so progress updates appear immediately. Most languages buffer by default.

Handle errors gracefully

Always report errors with clear descriptions. Include troubleshooting hints in error messages.

Validate input

Check that required parameters are present. Fail fast with helpful error messages.

Use temp directory

Write all output files to the current working directory. xyOps cleans up automatically.

Test edge cases

Test with missing files, invalid parameters, and network failures. Your plugin should never hang.

Document parameters

Use clear parameter titles and include examples in your plugin notes.

See also

• Marketplace - Discover and publish plugins
• Data Formats - Wire protocol specification
• Workflows - Chain plugins together
• Secrets - Inject credentials securely