Managed Python and Node runtimes

The RouteSpear SDKs always ship with the script plugin. Managed runtimes are an optional way to install Python and Node.js themselves. A compatible agent downloads a selected interpreter into its own versioned directory and supplies the bundled SDK automatically on every check. No pip/npm installation or SDK path configuration is needed.

Enable during installation

In Settings → Agents → Add agent → Setup, choose Built-in JavaScript + host interpreters, then enable Allow RouteSpear to manage Python and Node.js. Choose a managed version for either language. Use installed keeps that language on the operator’s existing interpreter mapping.

The generated installation package includes this permission and the selected versions. Each agent downloads them on its first normal startup. A reusable package applies the same initial choice to every new device. For image deployments, downloads happen when each clone starts. Existing runtime selections survive service restarts and are not reset by the initial installation flags.

The option requires a release advertising managed runtime support. The current catalog includes Windows, Linux and macOS on amd64 and arm64. Linux builds need a compatible glibc environment; Alpine/musl and vendor appliance packages are not covered. A runtime health check must pass on the actual host before activation.

Enable an existing agent

The host operator adds -script-managed-runtimes to the service’s arguments alongside -script-execute-inline and the configured script plugin, then restarts the agent. This local permission defaults to off. Portal and fleet commands cannot grant it remotely.

The optional -script-runtime-initial argument accepts comma-separated python@VERSION,node@VERSION entries from that agent release’s catalog. It only seeds an installation with no runtime selection file. Prefer selecting versions in the portal so the available versions and platform are validated.

Managed runtimes need outbound HTTPS access to their publisher download hosts and write access beneath the agent executable directory. Downloads go to script-runtimes, separate from machine-wide installations and PATH.

Select and update versions

Open the agent’s Configuration → Python & Node runtimes section in the portal, or the corresponding section on its admin fleet page. Select the Python and Node.js versions together and choose Apply versions. The full selection is applied as one operation; selecting Use installed removes that language’s managed override.

Versions stay pinned until an operator changes them. New versions become available through the catalog included with RouteSpear releases. Upgrade the agent when a selected version is absent from its own catalog. There is no background interpreter update schedule.

For each selected interpreter the agent:

1. Accepts a version from its embedded catalog, never a script-supplied URL.
2. Downloads over HTTPS and checks the exact size and release-pinned SHA-256.
3. Extracts into a staging directory with archive path and size restrictions.
4. Checks the interpreter version and required standard-library modules.
5. Atomically switches the selection only after every selected runtime passes.

Node archives come from Node.js releases. Python archives come from Astral’s python-build-standalone releases. The hashes are embedded in the RouteSpear release; they are not supplied by a remote configuration command.

Running checks, failures and rollback

Each new check resolves the selected executable once. A change does not restart the agent, replace files underneath a running script or interrupt in-flight checks. SDK imports, args, secrets and metric emission work with either managed or installed interpreters.

A download, checksum, extraction or health-check failure leaves the active selection unchanged. Review the command outcome, correct network, disk or host compatibility problems and retry. A first-start download failure is logged and the agent continues running; select the desired versions again in Configuration.

Restore previous selection restores the selection shown above that button, including Use installed choices. It rechecks the target runtimes before switching. The agent rejects stale edits if another operator changed the selection in the meantime. Refresh before retrying.

Old version directories are retained for rollback and running processes; automatic disk cleanup is not included. Do not edit a managed runtime’s files or install pip/npm packages into it. Extra dependencies require an operator-provisioned environment selected through Use installed. Bash and PowerShell also remain operator-installed. Removing a managed override does not install a system interpreter: that interpreter must already be configured.

This reference describes the source implementation. The installed agent’s reported permission, versions and command outcomes determine what is available on a particular machine.