Run work on an executor
Having an executor online doesn’t move any work to it. You choose what runs there, step by step.
How the decision is made
Every code node and every tool call asks the same question: local or remote? qRaptor answers it by checking three places in order and taking the first one that gives a definite answer.
- The step’s own setting. A code node’s Execution Location, or a tool’s. If it says Local or Remote, that’s the answer.
- The project default. The Default Execution Location selector on the Remote Executors page. Only Remote changes anything here; Local and Auto both mean “keep it on the platform”.
- Local. If nothing above asked for remote, the step runs on the hosted runtime.
In practice that means: the default is local, and things go remote because you asked for it. A project can have executors online for months and send them nothing until someone ticks Remote on a node.
Choosing an executor
Once a step is going remote, qRaptor picks which executor handles it:
- If the step names a Target Executor, it goes there. If that executor isn’t online, see below.
- If it doesn’t, the work is spread across the project’s online executors in rotation.
Only executors that are Online are eligible. Ones that are offline, draining or disabled are skipped.
Pin a Target Executor when the work depends on where it runs — a database only one host can reach, a GPU, a Python package installed on one image. Leave it unpinned when any of your executors could do the job and you’d rather spread the load.
When no executor is available
This is the part worth understanding before you go to production, because code nodes and tools behave differently on purpose.
| Step type | If it’s set to Remote and no executor is online |
|---|---|
| Code node | The node fails with a message saying no online executor was found. It does not run locally. |
| Custom tool | The tool falls back to the platform and runs locally — unless it’s pinned to a specific executor, in which case it fails. |
The reasoning: a code node marked Remote is usually reaching something only that network can see, so running it on the platform would either fail confusingly or, worse, quietly do the wrong thing. A tool that was merely load-balanced onto an executor can often run just as well on the platform, so it’s allowed to.
When a tool does fall back and then fails locally, the error keeps the original remote failure attached, so you can see what actually went wrong first.
The project default
The Default Execution Location selector sits at the top of the Remote Executors page and applies “when nodes don’t specify a location”.
Setting it to Remote is a big switch — from then on every code node and tool in the project that hasn’t been explicitly set to Local will look for an executor. It’s useful when a whole project exists to run inside your network, and risky otherwise. Most projects are better served by leaving it on Local and marking individual steps.
Auto (route by policy) is reserved for policy-based routing and currently behaves the same as Local.
Where to set it
- Code nodes — a script in a Task Agent.
- Custom tools — a tool your agents call, including HTTP tools pointed at internal services.
- MCP servers — an MCP server that only exists inside your network.
Next
- Code nodes — the most common starting point.