Manage executors

Day-to-day operation: knowing what state an executor is in, changing what you can change, and taking one out of service.

The executor list

Remote Executors shows every executor in the project as a card with its status, labels, concurrency, type and last heartbeat. The search box matches names and label values, which is the quickest way to find one host among many.

Reading status

Status	Meaning
Online	Connected and taking work.
Not yet connected	Created in Studio, but its agent has never dialled in. The card reads “Waiting for this executor to connect for the first time.”
Offline	Has connected before and isn’t connected now. Set automatically when heartbeats stop for about a minute.
Draining	Finishing its current jobs and taking no new ones. See below.
Degraded	Still connected but under strain — sustained CPU above 90%. It keeps taking work and returns to Online on its own once CPU recovers.

Only Online executors receive work. The distinction between Not yet connected and Offline matters when you’re debugging: the first means the agent was never started or has never successfully authenticated, the second means it worked before and stopped.

The detail page

Click an executor to open it. Three tabs: Overview, Executions and Metrics. Executions and Metrics are covered in Monitor executions.

An executor's Overview tab showing Configuration, System Info, Labels and Capabilities

Overview shows four cards:

Configuration — type, max concurrency, default timeout, whether it’s enabled.
System Info — OS, architecture, Python version, memory and CPU cores, as reported by the host. Before the first connection it reads “Appears once this executor connects for the first time”.
Labels — the tags from the executor’s LABELS variable.
Capabilities — what the agent advertised it can do, such as script execution, system tools and file transfer.

What you can change, and what you can’t

This is the part that surprises people, so it’s worth stating plainly.

Setting	Owner	How to change it
Name	qRaptor	Edit on the detail page. Persists across reconnects and restarts.
Description	qRaptor	Edit on the detail page.
Labels	the executor	Change `LABELS` where it runs, restart.
Jobs at the same time	the executor	Change `CONCURRENCY` where it runs, restart.
Capabilities	the executor	Determined by how the agent is configured.

The executor reports labels, concurrency and capabilities every time it connects, so those are facts about the running agent rather than settings the platform can impose. The UI says so on each card — “Labels come from the executor itself. To change them, update LABELS in its start command and restart it.”

Name and description are the opposite: they’re yours, they live on the platform, and a reconnecting executor won’t overwrite them.

Drain

Drain appears on the ⋮ menu and on the detail page while an executor is Online. It tells the executor to stop accepting new work and finish what it’s already running.

⚠️

Drain is a graceful shutdown, not a pause. Once the last in-flight job finishes, the agent disconnects and the process exits. There’s no “resume” — bring it back by restarting the container or service, which reconnects it as Online.

Use it before taking a host down for maintenance, so no work is cut off mid-run. If you just want to stop sending work to an executor without stopping it, change the code nodes and tools that target it instead.

Delete

Delete removes the executor from the project. The confirmation warns that “Its API keys will be revoked too.”

Delete when a host is gone for good. If the agent is still running somewhere it will no longer be able to authenticate, so stop the container too.

Common issues

Two executors appeared for one container — each API key binds to one executor. Two hosts sharing a key, or a key reused after deleting an executor, can produce this. Give each host its own key.
The name reverted to something like a container ID — that was old behaviour and is fixed. If you still see it, the executor connected before it was created in Studio; rename it on the detail page and it will stick.
Max Concurrency isn’t editable — by design. Change CONCURRENCY where the executor runs and restart it.
Stuck on Draining — that’s the resting state after a drain completes. Restart the agent to bring it back.

API keys — rotating and revoking credentials.