Code nodes

By the end of this page a Code node in your Task Agent will run its Python on your own executor instead of the hosted runtime.

Prerequisites

An executor showing Online — see Install & connect.
A Task Agent with a Code node. See Code node.

Point the node at an executor

Open Advanced Settings

Select the Code node in the builder and expand Advanced Settings in its panel. Execution Location is near the bottom, below the error-handling options.

Choose where it runs

Option	Effect
Auto (Routing Rules)	Defers to the project default. Today that means it runs locally unless the project default is Remote.
Local (qRunX)	Always runs on the hosted runtime, whatever the project default says.
Remote (qRemoteX)	Runs on one of your executors.

The Execution Location selector in a Code node's Advanced Settings

Pick a target, or don’t

Choosing Remote reveals Target Executor. Leave it on Any (use routing rules) to let qRaptor spread work across whichever executors are online, or pick one by name to pin the node to it.

Only online, enabled executors are listed. Pin when the script needs something specific to that host — a database only it can reach, a GPU, an installed package. Leave it open otherwise.

The Target Executor selector shown after choosing Remote

What changes for your code

A remote script runs in a separate process on your machine, not in the platform’s runtime. Two consequences matter.

⚠️

The ctx object isn’t available remotely. ctx["db"], ctx["llm"] and ctx["config"] are platform-side conveniences and don’t exist on an executor. Use {'{{'} config.xxx {'}}'} templates in your code instead — those are resolved on the platform before the script is sent, so the value arrives already substituted.

Your packages, not ours. The script runs against whatever Python environment the executor has. If it imports pandas, the executor needs pandas — either baked into a custom image or passed via QRAPTOR_EXTRA_PACKAGES. The platform’s allowlist of pre-installed packages doesn’t apply.

What stays the same: input variables arrive the same way, console.log() and friends still stream back into the run, and the node returns its result exactly as a local one does. Logs appear in the run as they’re produced, not in a batch at the end.

If no executor is online

The node fails. It doesn’t quietly run on the platform.

The error says the execution location is set to remote but no online executor was found. That’s deliberate — a node you marked Remote is usually reaching something only your network can see, so a silent local fallback would either fail in a more confusing way or produce a wrong answer against the wrong data.

If you’d rather a step degrade gracefully than fail, use a custom tool instead, which does fall back when it isn’t pinned.

Common issues

The node fails with “no online executor” — check the executor list. Anything not showing Online is skipped, including Draining.
KeyError on ctx — the script is using ctx["db"], ctx["llm"] or ctx["config"]. Switch to {'{{'} config.xxx {'}}'} templates.
ModuleNotFoundError — the package isn’t installed on the executor. Add it to the image or to QRAPTOR_EXTRA_PACKAGES, then restart.
The Target Executor list is empty — no executors are online right now.

Custom tools — the same idea for tools, with different fallback behaviour.