Run External Program

Category: System

Runs `program` as a direct executable path plus an argument list; it does not parse a shell command line. The block flushes pending Premiere actions and buffered file writes before the process starts, so external tools can see files written by earlier blocks. After the process exits or fails, cached text/spreadsheet file reads are invalidated so later file reads can observe external changes on disk. The process returns `exitCode`, `stdout`, and `stderr`; each can be stored in a variable when the corresponding store field is set. External programs are not constrained by Automation Agent filesystem block permissions. In production, grant only reviewed executables through `externalProcess.executableAllow`. `program` may be an executable path, a reviewed tool token, or an ABSCRIPT materialized `embedded://...` bundled asset reference such as `embedded://tools/mac/ffmpeg`.

Inputs

Input	Required	Value Kind	Types	Enum Values
program	yes	expression	string	—
args	no	array	—	—
cwd	no	expression	—	—
timeoutMs	no	expression	—	—
maxOutputBytes	no	expression	—	—
mirrorStdoutToConsole	no	expression	—	—
mirrorStderrToConsole	no	expression	—	—
storeExitCodeIn	no	variable-name	—	—
storeStdoutIn	no	variable-name	—	—
storeStderrIn	no	variable-name	—	—

Notes

• Runs program directly as an executable path with an argument array. It is not a shell command string.
• args are passed as process arguments and should not include shell quoting.
• When program is resolved from runtime.python, put -I first in args to isolate Python from PYTHONPATH, PYTHONHOME, user-site packages, and the launch CWD. Isolated mode also enables safe-path behavior, so helpers that import sibling modules must add their reviewed script directory to sys.path explicitly or use a packaged module layout.
• Before launching the process, the runtime commits pending Premiere actions and flushes buffered text/spreadsheet file writes.
• After the process exits or fails, the runtime invalidates cached text/spreadsheet file reads so later file reads can observe external changes on disk.
• storeExitCodeIn, storeStdoutIn, and storeStderrIn independently capture the process result.
• mirrorStdoutToConsole and mirrorStderrToConsole request live visibility while the process runs. The block remains blocking and final store outputs keep the same contract. A host that cannot preserve final output and exit-code semantics with live mirroring must fail clearly or fall back only when that behavior is documented for the caller.
• program may be:
  • an installed executable path,
  • a reviewed tool token resolved by the host,
  • an ABSCRIPT materialized bundled asset reference such as embedded://tools/mac/ffmpeg.
• External programs are not constrained by Automation Agent filesystem block permissions. A permitted executable can read and write using the operating system permissions of the host process.
• Production policies should grant reviewed executables explicitly with externalProcess.executableAllow. If this allow-list is absent or empty, external process execution is denied.
• externalProcess.cwdAllow can restrict the optional working directory, but it does not sandbox the launched process.
• timeoutMs and maxOutputBytes are process-call limits, not permission boundaries. externalProcess.maxTimeoutMs and externalProcess.maxOutputBytes are optional policy caps that reject runExternalProgram calls exceeding them; blank policy caps do not set defaults. These caps are separate from askAgent.timeoutMs.