Run Script job
Behavior-level reference for diagnosing Run Script jobs.
Task walkthrough: Run a script. This page is the full configuration and troubleshooting reference.
The Run Script job runs an embedded script — PowerShell, Bash, Python, or Shell — on the
agent machine. It's a built-in job type (builtin:script), so no setup or connection is
required. Use it instead of Run Command when the logic is more than a single command line.
| Property | Value |
|---|---|
| Job type | Run Script (run-script) |
| Runs on | Universal Agent only |
| Operating systems | Windows, Linux, macOS |
| Connections required | None |
| Category | Script |
How it works
The script content is written to a temporary file on the agent, run with the matching interpreter, and the temporary file is removed afterward. The interpreter must be installed on the agent — OpCon Continuum does not provide it.
| Script type | Interpreter used | Notes |
|---|---|---|
powershell | powershell.exe on Windows, pwsh on Linux/macOS | Run with -NoProfile -NonInteractive -ExecutionPolicy Bypass. pwsh (PowerShell 7+) must be installed on non-Windows agents. |
bash | /bin/bash | Bash must be present. |
python | python on Windows, python3 on Linux/macOS | Python must be installed and on PATH. |
shell | cmd.exe on Windows, /bin/sh on Linux/macOS | Default. Always present on the matching OS. |
Standard output and standard error are captured; standard error is appended under a
--- STDERR --- marker. The agent sets OPCON_WORK_ITEM_ID and OPCON_CORRELATION_ID for the
script, and filters sensitive environment variables exactly as Run Command does.
Configuration reference
| Parameter | Type | Required | Default | Limits | Notes |
|---|---|---|---|---|---|
scriptType | string | Yes | shell | one of powershell, bash, python, shell | Selects the interpreter. |
script | string | Yes | — | 1–65,536 chars | The script content. A longer script is refused as an invalid parameter. |
arguments | list of strings | No | none | ≤100 items, each ≤8192 chars | Passed to the script. |
workingDirectory | string | No | agent working directory | ≤4096 chars | Directory to run in. |
environment | name→value map | No | none | each value ≤32768 chars | Extra environment variables. |
failOnError | boolean | No | true | — | true fails the job on a non-zero exit code; false never fails it on its exit code. Ignored when exitCriteria is set. |
exitCriteria | list of conditions | No | none | ≤5 conditions | Exit codes that mean failure. See Deciding success. |
outputParsing | list of rules | No | none | ≤5 rules | Search the job output for text and set an exit code. See Deciding success. |
Every Run Script job has a fixed one-hour timeout. The platform sends every Universal Agent job with a 3,600-second limit, and no setting on the job changes it. At the hour the agent stops the script (graceful stop, then a forced stop after 5 seconds) and the job fails with Script exceeded its timeout of 3600s and was terminated. Kill does not reach a Universal Agent, so it does not stop the script sooner — see How a Universal Agent takes and runs work.
Deciding success: exit criteria and output parsing
By default the job succeeds on exit code 0 and fails on anything else. Exit criteria and
output parsing replace that rule when the script's own convention is different — an exit 3 that
means "nothing to do", or a script that exits 0 and prints an error.
Run Script and Run Command share one evaluator, so the rules below are identical on both job types. In short:
- Output parsing searches the job output and may rewrite the exit code. It never decides the outcome by itself.
- Exit criteria judge the resulting code — the effective exit code — and decide failure.
Exit criteria
Each condition is an operator and a whole number, and a condition that matches means the job
failed. Equal To 5 means fail when the script exits 5, not succeed when it does.
| Field | Values |
|---|---|
| Operator | Equal To, Not Equal To, Less Than, Greater Than, Less Than or Equal To, Greater Than or Equal To |
| Value | A whole number from −2,147,483,648 to 2,147,483,647 |
- Conditions are OR-ed: the first one that matches fails the job. If none matches, the job finished OK — including on a non-zero code.
- Up to five conditions. Leave the list empty to keep the default rule.
- With conditions set, Fail on Error is ignored — the criteria are the rule.
Output parsing
Each rule searches the job output for text and, when it matches, sets an exit code that the exit criteria then judge.
| Field | Values |
|---|---|
| Search operation | Contains or Does Not Contain |
| Text to find | 1–255 characters |
| Exit code to set | A whole number in the same range as above |
- Rules are evaluated in order, and the first match wins — later rules aren't consulted.
- Both standard output and standard error are searched.
- Matching is case sensitive and supports
*(any run of characters) and?(exactly one character). It is not a regular expression, so.,\and(are literal text. - A wildcard never spans a line break, so a search string containing a newline can never match.
- Up to five rules.
The agent keeps the first 512 KB and the last 512 KB of standard output, and the same of standard error. A script that produces more than 1 MB on a stream has its middle dropped, and a match that appears only there is missed. When that could have changed the outcome, the job output opens with a note saying so — so treat output parsing as unreliable on a script that logs heavily, and have the script print less instead.
Unlike a command, a script can choose its own exit code — exit 8 costs one line. Exit criteria and
output parsing earn their place when the script is one you can't change, or when the interesting
signal is only in its output.
Outcomes
The effective exit code below is the script's own code, or the code an output-parsing rule set.
| Result | Exit code | When |
|---|---|---|
| Success | 0 | Script exited 0, with nothing configured to say otherwise. |
| Success despite a non-zero exit | the effective code | Exit criteria are set and none matched, or failOnError is false. |
| Failed — exit criteria matched | the effective code | A condition matched the effective code. |
| Failed — script error | the script's code | Script exited non-zero, no exit criteria are set, and failOnError is true. |
| Failed — invalid parameters | 1 | A parameter fails validation: an empty script, an unknown scriptType, a value over its limit, more than five conditions or rules, an unrecognised operator, or a value outside the whole-number range. |
| Failed — interpreter missing | 1 | The interpreter for the chosen script type is not installed on the agent. |
| Failed — output parsing could not finish | the script's own code | A rule's search could not complete within the agent's matching budget. |
| Stopped — timeout or cancel | 128 | The agent terminated the process. Criteria and rules are not applied — a job the platform stopped always fails. |
- A process ended by a signal reports exit code 128, and that cannot be told apart from a process
that genuinely exited
128. - A job that fails with exit code 0 shows its return code as — rather than
0, so a failed job never displays a code that reads like success.
The job's Termination text names what decided the outcome — the rule that fired, the criterion that matched, or the script's own code — followed by whatever the script wrote to standard error.
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Job fails immediately with "Invalid task definition" | script empty, scriptType not one of the four values, or a value over its limit | Correct the parameters (Builder). |
| Job fails to start a PowerShell script on Linux/macOS | pwsh (PowerShell 7+) is not installed on the agent | Install pwsh on the agent, or use a different script type (Administrator / Builder). |
| Python script won't start | python/python3 not installed or not on PATH on the agent | Install Python on the agent and confirm it's on PATH (Administrator). |
| PowerShell script behaves differently than in an interactive console | The script runs with -NoProfile and -ExecutionPolicy Bypass | Don't rely on profile setup or local execution policy; make the script self-contained (Builder). |
| Script can't see an environment variable (often a password/secret) | Filtered by design (same rule as Run Command) | Pass it as a job Environment Variable, or use a connection-based connector for credentials (Builder / Administrator). |
| Job fails on a non-zero exit you consider acceptable | Fail on Error is on and no exit criteria are set | Set exit criteria that exclude that code, or turn Fail on Error off (Builder). |
| Job finishes OK on an exit code that should have failed it | Exit criteria are set and none of them matches that code — the criteria replace Fail on Error entirely | Add a condition that matches the code, remembering a match means failure (Builder). |
| An output-parsing rule never fires even though the text is in the output | The search is case sensitive, */? are the only wildcards, a wildcard can't cross a line break, or the text sits in the dropped middle of more than 1 MB of output | Match the case exactly, replace regular-expression syntax with */?, and have the script print less (Builder). |
| Job fails with "could not be evaluated within the allowed matching budget" | A long search string containing ? against output with a long repeating run | Replace the ? with *, which makes the search efficient (Builder). |
| Job ends after one hour with exit code 128 | The script ran past the fixed one-hour timeout and was stopped | The limit can't be raised. Split the work, or make the script finish within the hour (Builder). |
| Job fails with "Invalid task definition" on a long script | The script is over 65,536 characters | Shorten the script, or split it across jobs (Builder). |
| Job assigned but never runs | Target agent is not a Universal Agent | Reassign to a Universal Agent. |
Contact support when
- A script fails to start even though its interpreter is installed and runs the same script manually on the agent.
- Output or exit codes don't match what the script actually produces.
Include the job output, the scriptType, the agent OS, and confirmation that the interpreter
is installed on the agent.