Script arguments, context and secrets

The runtime has three distinct inputs: non-secret JSON arguments, a read-only execution context, and explicitly named credentials. No template expansion is performed inside args. Read context fields with the SDK instead.

Helper equivalents

Operation	JavaScript / Node	Python	Bash	PowerShell
Arguments	rs.args()	rs.args()	rs_args	Get-RsArgs
Context	rs.context()	rs.context()	rs_context	Get-RsContext
Target	rs.target()	rs.target()	rs_target	Get-RsTarget
Check ID	rs.testId()	rs.test_id()	rs_test_id	Get-RsTestId
Runtime budget in ms	rs.timeoutMs()	rs.timeout_ms()	rs_timeout_ms	Get-RsTimeoutMs
Named credential	rs.secret(name)	rs.secret(name)	rs_secret NAME	Get-RsSecret -Name NAME

Arguments

Enter a JSON document in Args (JSON). Objects are convenient, but the runtime accepts any valid JSON document within 16 KiB. Match the shape your code expects:

{"queue":"orders","warn_depth":100,"include_consumers":true}

import routespear as rs
settings = rs.args()
queue = settings.get("queue", "orders")
warn_depth = float(settings.get("warn_depth", 100))

The parsed SDKs read and cache stdin when first called. Empty input gives {}. Malformed JSON raises a parse error; it is not silently repaired. Do not consume stdin before calling the helper. Bash returns raw JSON text and leaves parsing to the caller; cache that output once because command substitutions run in subshells and do not preserve the helper’s cache in the parent shell.

Args are saved configuration, not a secret channel. Use reference names for credentials. A signed bundle receives params only if its manifest permits them.

Full context schema

{
  "agent": {
    "id": "agt_example",
    "hostname": "collector-1",
    "version": "example-version",
    "labels": {"site":"office"}
  },
  "test": {
    "id": "tst_example",
    "target": "api.example.com",
    "labels": {"service":"orders"},
    "timeout_ms": 7000,
    "interval_ms": 60000,
    "language": "python"
  },
  "run": {
    "invocation_id": "example-invocation",
    "started_at": "2026-10-03T12:00:00Z"
  }
}

These values are illustrative. Read the actual context instead of hard-coding IDs.

Field	Type / meaning
agent.id	Executing agent identity.
agent.hostname	Reported machine hostname.
agent.version	Agent version string.
agent.labels	Map of the executing agent’s labels.
test.id	Check ID, not its parent test-group ID.
test.target	Configured target; may be empty for a local script.
test.labels	Check labels.
test.timeout_ms	Effective script runtime budget in milliseconds.
test.interval_ms	Configured invocation interval in milliseconds.
test.language	Present for inline scripts.
test.bundle, test.revision	Bundle name and signed revision for bundle runs.
run.invocation_id	Identity of this execution.
run.started_at	Run start time in RFC 3339 form.

Context contains no tenant identifier, enrollment material, other checks or credential values. Fields are additive; tolerate absent optional values. JavaScript/Node/Python normalize missing agent, test, run and label maps. PowerShell and Bash expose the supplied document more directly; check for fields when testing outside an agent.

Credential references

Configure this under Advanced → Credential references:

{"api_token":"svc_readonly_token"}

api_token is the name the script reads. svc_readonly_token is the agent-local store reference. Neither is the value. The operator must configure the local secret provider and allow the reference with -script-secrets. Without that allowlist, the run is refused before code starts. Scripts cannot use the centrally shared-secret delivery system.

There are at most 16 mappings. Script-side names use [a-z][a-z0-9_]* and are at most 64 characters. Store references use [A-Za-z0-9_.-], are 1–128 characters and cannot contain ... Store keys are not paths.

token = rs.secret("api_token")
# Use token only in the authenticated request; do not emit or log it.

Values are resolved before execution and supplied through a credentials file. The SDK reads only the declared map; it does not query a general secret store. Missing names throw an error in JavaScript/Node/PowerShell, raise KeyError in Python, and return nonzero in Bash. File/JSON read errors also fail. Do not turn missing credentials into a successful health result.

Environment supplied by the runtime

The agent sets these variables on each script process automatically. This is a reference for script authors, not a machine-setup checklist. Do not create SDK directories, persist a run’s temporary path, or set SDK environment variables on the host. The SDK files are already included in the script plugin.

Variable	Meaning
ROUTESPEAR_SCRIPT_SDK	Directory containing the SDK modules.
ROUTESPEAR_SCRIPT_LANGUAGE	Selected inline language.
ROUTESPEAR_SCRIPT_TARGET	Configured target.
ROUTESPEAR_SCRIPT_TEST_ID	Check ID.
ROUTESPEAR_SCRIPT_TIMEOUT_MS	Effective wall-clock budget.
ROUTESPEAR_SCRIPT_CONTEXT	JSON context above.
ROUTESPEAR_SCRIPT_CREDENTIALS	Credentials-file path when references are supplied.
PYTHONPATH, NODE_PATH	Include the SDK directory for the relevant host import.

Prefer SDK helpers over parsing these variables yourself. The built-in engine does not expose Node’s process.env; its helpers provide these inputs directly. The host process environment is constrained; do not assume interactive shell settings, proxy variables or installed packages will appear automatically.