Run script

How the Run script action starts your own PowerShell or Bash script, passes values back and when the step fails.

Use this action to run your own PowerShell or Bash script on the device and pass values from it to later steps. The device must be online.

Prerequisites

An octoja agent must be installed and connected on the target device.
For Logged-in user under Run as, someone must be signed in to the device. On Linux and macOS, that must be an account other than root.
On Linux, octoja needs jq on the device to capture output parameters. Without jq, they stay empty.

Configuration fields

Field	Type	Required	Default	Description
Windows (PowerShell)	script	No	—	Script for Windows devices. Runs with PowerShell 7 if it is installed on the device, otherwise with Windows PowerShell 5.1. `#requires` directives don't work. Variables `${{ … }}` are allowed
Linux (Bash)	script	No	—	Script for Linux devices, run with `bash`. Variables `${{ … }}` are allowed
macOS (Bash)	script	No	—	Script for macOS devices, run with the system's `bash`. Variables `${{ … }}` are allowed
Run as	enum	No	System (agent identity)	With System (agent identity), the script runs as `SYSTEM` on Windows and as `root` on Linux and macOS. With Logged-in user, it runs in the signed-in user's session
Working directory (optional)	text	No	—	Folder the script starts in. If the folder doesn't exist on the device, the script starts without changing folder. Variables `${{ … }}` in the field are resolved
Script timeout in seconds (optional)	number	No	`240`	How long the script may run before the agent stops it. Allowed: 10 to 7,200 seconds (two hours). Other values can't be saved
Output parameters	list of name and type	No	—	Variables from your script that octoja captures after the script ends. Add a row with Add output parameter. Pick Text (default), Number or Boolean as the type. See the rules below

The three script fields are tabs in the properties panel. Each device runs only the script for its own operating system, so fill in only the tabs you need.

octoja inserts variables into the script as plain text before sending it to the device. If a value doesn't exist in the run, for example because the step that produces it was skipped, the token stays in the script unchanged.

Warning: octoja does not escape values for PowerShell or Bash. Quotes, ; or $( … ) in a value become part of the script and can change what it does. Only insert values you control, such as your own custom fields. Never put free text from users or external systems into a script.

Output parameters

Declare a name such as result under Output parameters, then set a variable with the same name in the script: $result = 'OK' in PowerShell or result='OK' in Bash. Text you only write to standard output does not set a parameter.

Rule	Details
Allowed names	Letters, digits and underscores only. octoja ignores other names. On Windows, names are case-insensitive
Reserved names on Windows	If a parameter is named like a built-in PowerShell variable, such as `input`, `args`, `error` or `host`, the step fails before your script starts
Built-in names	Don't use `exitCode`, `success`, `stdout`, `stderr` or `runtimeMs`. The built-in output always wins
Count	Up to 100 parameters per step
Value type	All values arrive as text. The type only controls how the variable picker and conditions treat the value. It doesn't convert or validate anything

Platform support

Platform	Supported
Windows	Yes
Linux	Yes
macOS	Yes

Outputs

Output	Description
`exitCode`	The script's exit code. `-1` if the script timed out or couldn't start
`stdout`	The script's standard output
`stderr`	The script's error output
Your output parameters	Each declared parameter, under the name you gave it

Insert variable offers exitCode, stdout and stderr (as Exit code, Standard output and Error output) plus your own parameters.

Result behaviour

Case	Result
Exit code `0`	Succeeded.
Any other exit code	Failed with `Script exited with code <code>.` Outputs and output parameters are still captured.
No script for the device's platform	Succeeded without running anything. `stderr` contains `No script configured for this platform.`
Script exceeds the timeout	Failed. The agent stops the script, `exitCode` is `-1` and `stderr` mentions the timeout.
Logged-in user with nobody signed in	Failed.
Device offline when the step starts	Device offline. Depending on If device is offline, the run ends with this status or the step is skipped.
No answer from the device	Timed out.

With the default On failure setting, a failed step stops the workflow. If later steps should run anyway, choose Continue to next step.

Standard output, error output and output parameters are cut off after 65,536 characters, and the result doesn't tell you. Even a successful step can return incomplete output, so return compact results rather than full logs.

With System (agent identity), the script runs with full rights and can change or delete anything on the device. Test step and Test run really execute it. Try new scripts on one suitable device first.

FAQ

Can the action run through a network device's monitoring device?

No. Run script uses the target device's agent connection. For an agentless network device, the assigned monitoring device does not execute automation scripts on its behalf. An online status for the network device does not replace an agent connection.

This differs from monitoring checks for network devices, which can run through the monitoring device. Write custom field instead runs inside octoja and needs no agent connection; that action does not itself execute a PowerShell or Bash script.

Why is error output empty even though the script failed?

A nonzero exit code indicates failure but does not itself write any text to stderr. In Bash, echo "Example failure" writes to stdout, not stderr. Check both outputs; empty error output does not mean the script succeeded.

If your Bash script should return its own error message, write it explicitly to error output:

echo "Example failure" >&2
exit 1

For a later Teams message, choose Continue to next step under On failure on the script step. On the notification step, add two conditions for the script's Exit code: is not empty and ≠ 0, combined with All. This prevents a skipped script step from triggering a failure notification.

Use Insert variable to include its Exit code, Standard output and Error output in the message. You do not need to declare your own output parameters for these values.

See also: Create an automation

Was this helpful?

Still need help? Ask the team