← Back to Blog

Run Local Scripts from an AI Agent — Python, Node.js, PHP, Java

The shell connector lets an OE Runtime agent run any script or command directly on the machine it's deployed on — no SSH tunnel, no HTTP wrapper. Two files and the agent handles the rest.

What You Need

• Node.js 18+ installed, or the OE Runtime binary from openenthrium.com/runtime
• An API key from OpenAI, Anthropic, or any supported LLM provider
• Local scripts you want the agent to run — Python, Node.js, PHP, Java, Bash, or any CLI tool
• A text editor — nothing else

---

What the Shell Connector Does

Every OE Runtime connector exposes tools the LLM can call. The shell connector exposes one tool: run_command. The agent passes a command string, the connector runs it via the system shell, and returns stdout, stderr, and the exit code back to the LLM.

The agent can run any command the host machine supports:

Shell vs SSH — Which to Use

	shell connector	ssh connector
Runs on	Same machine as OE Runtime	Any remote server over SSH
Credentials needed	None — just a working directory	Private key or password
Network required	No	Yes
Best for	Local scripts, ETL, file processing	Remote server admin, log inspection

Step 1 — Create the Skill Files

Create a folder called shell-scripts/. Add SKILL.md with the shell instructions and a slim agent.yaml that wires the skill to the shell connector:

---
name: local-exec
description: Run Python, Node.js, and shell commands directly on this machine
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

You are a local automation agent. Use the Local Shell connector to run
commands on this machine. Run each command, capture the output, and
include results and exit codes in your final report.

## Step 1: Check runtimes
Run each of these commands one at a time and note the output:
  node --version
  python3 --version
Report which are available and their versions.

## Step 2: Run Node.js inline
Run this Node.js one-liner:
  node -e "const os = require('os'); console.log('hostname:', os.hostname()); console.log('platform:', os.platform()); console.log('cpus:', os.cpus().length);"
Report the output.

## Step 3: Run Python inline
Run this Python one-liner:
  python3 -c "import datetime, platform; print('date:', datetime.date.today()); print('python:', platform.python_version()); print('system:', platform.system())"
Report the output.

## Step 4: Report
Write a short summary covering: which runtimes are installed, the
Node.js system info, and the Python system info.

name: Local Script Runner
description: Run Python, Node.js, and shell commands directly on this machine
connectors:
  - connection_name: Local Shell
    connection_type: shell
skills:
  - path: ./
    trigger_type: auto

Step 2 — Create oe-config.json

Set cwd to the directory your scripts live in. Commands run from there by default. No credentials needed for the shell connector itself — just a working directory and an optional timeout.

{
  "llm": {
    "provider": "openai",
    "model":    "gpt-4o",
    "apiKey":   "sk-..."
  },
  "server": {
    "enabled": false,
    "port": 3333,
    "apiKey": "your-secret-api-key"
  },
  "connectors": [
    {
      "connection_name": "Local Shell",
      "connection_type": "shell",
      "cwd":     ".",   // working directory — "." = wherever you run from
      "timeout": 30    // seconds per command, max 300
    }
  ]
}

Step 3 — Run it

From the parent folder containing your shell-scripts/ directory:

npx -y @openenthrium/oe-runtime@latest ./shell-scripts

The agent checks runtimes, runs the Node.js and Python one-liners, reads their output, and writes a plain-English summary — all in one pass.

Point It at Real Scripts

Once the hello-world runs, swap the inline one-liners for real scripts in your project. Set cwd to your project root in oe-config.json and reference files by relative path in your SKILL.md:

## Step 1: Validate input
Run: python3 validate.py --file invoices/jan.pdf
If exit code is non-zero, stop and report the error message from stderr.

## Step 2: Process
Run: python3 process_invoice.py --file invoices/jan.pdf --out output/
Capture the output file path printed to stdout.

## Step 3: Report
Run: node generate_report.js --format pdf
Return the final output path and a one-paragraph summary of what was processed.

Unlike a plain cron job, the agent understands what the script returns. If validate.py exits with code 1 and prints ERROR: missing vendor field, the agent surfaces that clearly, skips downstream steps, and reports the specific issue — no conditional logic needed on your side.

Working Directory Override Per Command

The agent can also override the working directory per command — useful when scripts live in different sub-directories. In your SKILL.md, just tell the agent which directory to use:

## Step 1: Run ETL
Run this command with cwd set to /var/www/etl:
  python3 etl.py --date {{date}}

## Step 2: Run report
Run this command with cwd set to /var/www/reports:
  node daily_report.js

Combine with Other Connectors

The shell connector pairs naturally with every other connector. A common pattern: run a local script to generate data, then send the result somewhere.

connectors:
  - connection_name: Local Shell
    connection_type: shell
  - connection_name: Sales DB
    connection_type: postgresql
  - connection_name: Notify Bot
    connection_type: telegram

Steps: run the Python ETL script → write results to PostgreSQL → send a Telegram summary. One agent, three connectors, no glue code.

oe-config.json Field Reference

Field	Required	Description
connection_name	Yes	Must match connection_name in agent.yaml.
connection_type	Yes	"shell", "local-exec", or "local-shell" — all equivalent.
cwd	No	Working directory for all commands. Defaults to the directory OE Runtime was launched from.
timeout	No	Max seconds per command. Default 30, max 300. The agent can also set this per command.