Use in ToolGate

In the ToolGate console, open Server packages, then Marketplace, and install this package. These values identify exactly what you install:

{
    "marketplace": "olo-labs-marketplace",
    "packageId": "examples.scripts",
    "version": "0.1.0",
    "packageDigest": "sha256:d9b5dbc595d01620fb091258c42387ad50e4a7796624d7b3fad025e37a70c432"
}

Overview

Script runner

Tools: scripts.run, scripts.list. Part of the Java Tool SDK examples.

Runs a script an administrator has put in an allowlisted directory and returns its exit code and the last lines of its console output (stdout and stderr together). Works with Windows batch files (.bat, .cmd), PowerShell (.ps1) and shell scripts (.sh).

Safety

The caller names a script, never a command line. It must sit directly in ScriptsDir; names with a directory, .. or a link out of the directory are refused.
When AllowedScripts is not *, only the scripts it lists run.
Arguments are passed as separate argv entries and may hold only letters, digits, spaces and . _ : / \ = @ , + -, so nothing can be chained even through cmd.exe.
Scripts start with a minimal environment (PATH, and SystemRoot/ComSpec on Windows), never the tool's own.
A run past its deadline (timeoutSeconds, at most MaxRunSeconds) is killed with all its child processes. Only the last lines lines are kept in memory.
The tool is declared NON_IDEMPOTENT: a script may change things, so ToolGate will not retry it.

Settings

Globals unless marked. Set them in toolgate.dev.json for development, as TOOLGATE_GLOBAL_<NAME> (or TOOLGATE_DESTINATION_<NAME>, TOOLGATE_SECRET_<NAME>) for a standalone jar, or on the deployment under ToolGate.

Setting	Default	Meaning
`ScriptsDir`	`scripts`	Directory holding the scripts. Absolute under a Tool Host.
`AllowedScripts`	`*`	Comma-separated file names, or `*` for every script in the directory.
`MaxRunSeconds`	`50`	Upper bound on a run.
`ShellPath`	`/bin/sh`	Interpreter for `.sh`.
`CmdPath`	`C:\Windows\System32\cmd.exe`	Interpreter for `.bat` and `.cmd`.
`PowerShellPath`	Windows PowerShell 5.1	Interpreter for `.ps1`; point it at `pwsh.exe` for PowerShell 7.
`ScriptPathVariable`	`default`	`PATH` the script sees.

Try it

cp toolgate.dev.example.json toolgate.dev.json   # then edit it; never commit toolgate.dev.json
toolgate dev                                      # an MCP server over stdio
toolgate pack                                     # build/toolgate/script-runner-0.1.0.tgpkg

Things to ask a model connected to it:

"Run nightly-report.bat and show me the last 30 lines."
"Which scripts can you run?"

Source repository
License: Apache-2.0

Tools

scripts.list Read only: List scripts Lists the scripts callers may run with scripts.run.
scripts.run Non idempotent: Run a script Runs one of the administrator's allowlisted scripts (.bat, .cmd, .ps1 or .sh) and returns its exit code and the last lines of its console output.

Settings it needs

Name	Kind	Type	Default	Description
`AllowedScripts`	global	STRING	`*`	Comma-separated script file names callers may run, or * for every script directly in ScriptsDir.
`CmdPath`	global	STRING	`C:\Windows\System32\cmd.exe`	Interpreter for .bat and .cmd scripts.
`MaxRunSeconds`	global	INT	`50`	Upper bound on a run, whatever timeoutSeconds the caller asks for.
`PowerShellPath`	global	STRING	`C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`	Interpreter for .ps1 scripts. Set it to pwsh's path to use PowerShell 7.
`ScriptPathVariable`	global	STRING	`default`	PATH the script sees, or 'default' for the operating system's standard directories.
`ScriptsDir`	global	STRING	`scripts`	Directory holding the scripts callers may run. Use an absolute path under a Tool Host.
`ShellPath`	global	STRING	`/bin/sh`	Interpreter for .sh scripts.

Versions

Version	API change	Compatibility	Published
0.1.0	none	Java 17, protocol 2	15 Oct 2026 - 11:55

Publisher

ToolGate Examples, OLO Labs

Publisher details are supplied by the publisher. Validation checks package format, not code safety.

Scripts - ToolGate tool package