Add an executor

By the end of this page you’ll have an executor registered in Studio and an API key in your clipboard, ready to start the agent.

Prerequisites

The executor gateway is switched on for the project — see Turn on remote execution.

Two kinds of setting

The wizard’s first step asks for five things, and they behave differently. It’s worth knowing which is which before you fill it in:

Name and Description are stored in qRaptor. You can change them later from the executor’s detail page, and they stay as you set them.
Labels, jobs at the same time and the job timeout are not stored in qRaptor. They’re written into the install command you copy in the next step, as environment variables the executor reads when it starts. The executor is the source of truth for these — it reports them every time it connects.

The wizard says as much: “These become part of the install command you copy in step 3. To change them later, edit the command where the executor runs and restart it.”

That’s the mental model for the whole feature: name it in Studio, configure how it runs in the command.

Fill in step 1

Click Add Executor. The wizard is titled Setup New Executor and shows Step 1 of 3.

Name it

Under ① Name & Configuration:

Field	Notes
Executor Name (required)	How it appears everywhere in Studio. Pick something that says where it runs — the placeholder suggests Production VPC Executor. Next stays disabled until you’ve entered one.
Description	Optional. Useful when you have several — the placeholder suggests Runs in AWS us-east-1 VPC with GPU.

Step 1 of the Setup New Executor wizard showing the Executor Name and Description fields

Decide how it should run

The second half of the step is headed How this executor should run.

Field	Becomes	What it does
Labels	`LABELS`	Key/value tags describing the executor — its environment, region, hardware. They show on the executor’s card and detail page, and the executor list searches them, so they’re how you tell several executors apart at a glance.
Jobs to run at the same time	`CONCURRENCY`	How many scripts or tool calls this executor will run in parallel. Defaults to 25. Lower it on a small host.
Give up on a job after (seconds)	`EXEC_TIMEOUT_SEC`	How long a single job may run before the executor abandons it. Defaults to 300.

Add labels with Add Label and remove one with its ×.

The How this executor should run section with label pairs, jobs to run at the same time, and the job timeout

Generate the key

Click Next for ② Generate API Key.

Field	Notes
API Key Label	How the key appears on the API Keys page. Defaults to your executor’s name plus Key.
Expiry	No expiry, or Custom with a date. A key with no expiry is fine to start with — you can rotate or revoke it at any time.

Step 2 of the wizard showing the API Key Label field and the expiry options

Click Generate Key. The wizard moves to step 3 and shows the key once.

⚠️

One API key per executor. A key binds itself to the first executor that uses it, and two containers sharing one key will be treated as the same executor and fight over the connection. If you’re running several, give each its own key.

What exists now

Your executor appears in the list straight away, before you’ve started anything, marked Not yet connected with the note “Waiting for this executor to connect for the first time.”

That’s the expected state between finishing the wizard and starting the agent. It’s distinct from Offline, which means an executor that has connected before and isn’t connected now.

Common issues

Next is greyed out — the Executor Name is empty.
You want to change the labels or concurrency afterwards — edit the environment variables where the executor runs and restart it. Changing them in Studio isn’t possible by design; the executor reports its own values on every connect.

Install & connect — copy the command and bring it online.