Turn on remote execution
By the end of this page your project will have an executor gateway switched on, and you’ll have the connection URL that every executor you add will use.
Prerequisites
- Pro Pro plan or above.
- A project. Remote execution is enabled per project, not per workspace — a second project needs its own activation.
Activate the gateway
Open Remote Executors in the project sidebar. Until it’s switched on, the page shows a single card.
Read the endpoint
The card is headed Enable Remote Executors and explains what you’re turning on:
Activate the executor gateway to run agents on your own infrastructure — in your VPC, on-prem, or on GPU clusters. Your gateway endpoint will be:
Beneath it is the URL your executors will connect to:
wss://exec-{projectShortId}.qraptor.app/ws/executorThe exec- prefix plus your project’s short ID is what ties a connection to this project. An API key from one project can’t be used against another project’s URL.
Click Activate Gateway
Activation is instant and applies to the whole project.
What appears after activation
The page becomes the executor list, with three things worth noting at the top.
Gateway URL — the same wss://exec-… address, kept visible so you can copy it when configuring an executor by hand.
Default Execution Location — where code and tool steps run when nothing else specifies a location. It applies, in the UI’s words, “when nodes don’t specify a location”.
| Option | Effect |
|---|---|
| Local (hosted runtime) | Everything runs on the platform unless a node or tool asks for remote. This is the default and the right choice for most projects. |
| Remote (qRemoteX) | Code and tool steps go to an executor whenever one is online, unless a node or tool explicitly says local. |
| Auto (route by policy) | Reserved for policy-based routing. Today it behaves the same as Local. |
Leave this on Local while you set up. It’s a project-wide switch, and flipping it to Remote before you’ve confirmed an executor works will send every code node in the project to an executor that may not be there. Run work on an executor covers the safer per-node and per-tool settings.
Monitoring, API Keys and Add Executor — the actions along the top. You’ll use Add Executor next.
Activation isn’t instant everywhere. The gateway’s answer is cached for about five minutes, so an executor that tries to connect immediately after you activate may be refused for a few minutes before it succeeds on its own. If you’re setting up for the first time, activate first, then install — by the time you’ve generated a key and started a container, it will have caught up.
Common issues
- Remote Executors isn’t in the sidebar — the section is hidden on the Free plan.
- Nothing happens when you click Activate Gateway — the plan doesn’t include remote executors. They’re available on Pro and above; Free and Starter can’t activate.
- An executor is refused right after you activate — that’s the cache described above. It clears within about five minutes and the executor reconnects on its own; no action needed.
Next
- Add an executor — name it and generate its API key.