Script check parameters and execution

A script check has ordinary check identity, placement and scheduling fields, plus the params object below. Interval and Timeout in the editor are check-level values in seconds. params.timeout_ms is a separate optional limit in milliseconds; it can shorten the script’s effective deadline.

Complete params object

Parameter	Type and default	Meaning and constraints
language	String; required for inline code	Exactly js, node, python, bash or powershell. Must be absent/empty for bundles.
source	String	Inline source. Required with language; cannot coexist with bundle. At most 262,144 UTF-8 bytes; no NUL characters.
bundle	String	Installed signed-bundle name, without its extension. Required for bundle mode; cannot coexist with source or language. It is a name, never an executable path.
args	JSON document; omitted means no input	Non-secret configuration sent on stdin. At most 16,384 serialized bytes. Inline code accepts it; bundles must declare accepts_params. SDKs return an empty object when no input is available.
credential_refs	Object mapping names to strings; {}	At most 16 script-name → agent-store-reference pairs. Operator allowlisting is required. See credentials and context.
timeout_ms	Non-negative integer; 0/omitted uses the runtime default	Milliseconds. Cannot raise a signed-bundle timeout, agent ceiling or invocation deadline.
allow_coalescing	Optional boolean	false disables sharing for an eligible signed bundle. true does not grant eligibility. Inline scripts remain ineligible; a bundle also needs its signed side_effect_free declaration and the normal execution-equivalence checks.

Unknown parameter fields are ignored by the current decoder for forward compatibility. They do not provide new execution capabilities. Do not add interpreter paths, command-line flags or environment overrides here.

Inline example

{
  "language": "python",
  "source": "import routespear as rs\nargs = rs.args()\nrs.gauge('queue_depth', args['depth'], unit='count')\n",
  "args": { "depth": 12 },
  "timeout_ms": 5000
}

Bundle example

{
  "bundle": "disk-health",
  "args": { "mount": "/" },
  "credential_refs": { "api_token": "svc_readonly_token" },
  "timeout_ms": 5000,
  "allow_coalescing": false
}

The named bundle and reference must already exist on the executing agent. Neither JSON example installs code, grants execution or provisions credentials.

Runtime selection and prerequisites

Language/mode	Runtime selection	Required local grant
js	Bundled routespear-jsengine	-script-execute-js
python	Allowlisted python3, then python	-script-execute-inline
node	Allowlisted node, then nodejs	-script-execute-inline
bash	Allowlisted bash, then sh	-script-execute-inline
powershell	Allowlisted pwsh, then powershell	-script-execute-inline
Signed bundle	Interpreter named by its signed manifest	-script-execute, trust keys and bundle directory

The script plugin must be enabled. A language name never chooses an arbitrary binary. Host interpreters are resolved through -script-interpreters, with explicit name=/absolute/path mappings or the operator’s auto selection. PowerShell uses fixed -NoProfile -NonInteractive -ExecutionPolicy Bypass -File arguments; a check cannot change these flags. Packages used by host code must already be installed. The SDK itself is materialized into each run’s directory.

SDK setup requires no host configuration. The helper files are embedded in the script plugin. Every run gets a fresh copy, automatic PYTHONPATH and NODE_PATH, and the ROUTESPEAR_SCRIPT_SDK variable used by shell imports. The editor templates contain the import line. Updating the script plugin updates these helpers; there is no separately installed SDK package to maintain.

Interpreter installation is optional for Python and Node.js. On supported agents, the operator can allow managed runtimes and select a private, pinned interpreter. Otherwise, the agent’s auto mode only discovers installed interpreters. Install a supported interpreter where the agent service can find it. A runtime available only in your interactive user’s shell may be absent from the service’s PATH. Restart the service after installing a runtime or changing its environment so startup discovery can run again, or configure an explicit interpreter mapping. Extra pip/npm packages are also separate from the bundled RouteSpear SDK.

Managed Python overrides both python and python3; managed Node overrides both node and nodejs for subsequent runs. Returning a language to Use installed restores its original host mappings. Built-in JavaScript, Bash and PowerShell do not depend on the managed runtime selection.

The portal’s Custom scripts installation/reconfiguration options do not grant signed bundles or secret access. Remote reconfiguration is also bounded by the host’s -script-remote-max-mode; explicit local settings retain precedence. See agent configuration for the operator workflow.

Time and resource limits

Inline scripts without timeout_ms start from a 30-second runtime default. The effective deadline also considers the local maximum and the check invocation deadline, reserving three seconds for termination, cleanup and reporting. The calculation has a one-second floor. A bundle starts from its signed timeout (30 seconds if unset). The maximum runtime timeout is two minutes; the agent may impose a lower ceiling. Budget calls below the effective timeoutMs()/timeout_ms() value, not merely the editor’s check timeout.

Default script resource limits are 256 MiB of memory and 30 CPU seconds. The operator may lower limits through ROUTESPEAR_SCRIPT_MAX_MEMORY_BYTES, ROUTESPEAR_SCRIPT_MAX_CPU_SECONDS and ROUTESPEAR_SCRIPT_MAX_TIMEOUT_MS. Enforcement mechanisms differ by OS. Each invocation has a fresh working directory removed after the run; do not use it as persistent state.

Only the built-in JavaScript engine routes SDK network calls through RouteSpear’s target policy. A host interpreter uses its own networking libraries and OS permissions. All modes retain execution deadlines and output budgets, but they do not provide identical confinement. See the JavaScript API.

Signed manifest reference

An installed signed bundle contains routespear.json. Its fields are signed, unlike the check’s configurable params. Unknown manifest fields are rejected.

Field	Type / behavior
schema_version	Required integer 1.
name	Bundle name matching the installed artifact; at most 64 characters.
version	Human-readable version, at most 64 characters; not used for anti-rollback comparisons.
revision	Required unsigned integer ≥1; compared against operator revision floors.
description	Optional operator-facing description, at most 512 characters.
interpreter	Name from the local interpreter allowlist, never a path.
script	Bundle-relative regular-file path to the entry script.
args	Fixed process argument vector appended after the script path; at most 32 strings of at most 256 characters each. Distinct from check params.args on stdin.
timeout_ms	Signed deadline limit; 0 selects the default.
not_after	Optional RFC 3339 expiry instant.
accepts_params	Boolean, default false; permits the check’s JSON document on stdin.
side_effect_free	Boolean, default false; signer’s declaration required for sharing eligibility.
max_metrics	Tightens the per-run metric cap; 0 uses 256. Cannot exceed the plugin cap.

The manifest is capped at 64 KiB. Signature verification, expiry and revision validation happen before execution. Source support does not establish that a particular deployed agent has the required version, flags or installed bundle.

Continue with metric output and arguments, context and secrets.