Install & connect

By the end of this page the qRemoteX agent will be running on your infrastructure and showing as Online in Studio.

Prerequisites

You’ve finished step 2 and are looking at ③ Install & Connect with your API key on screen.
A host that can make outbound HTTPS connections. No inbound rules, no public IP.

🚨

Copy the whole command before you leave this screen. The API key is shown exactly once — qRaptor stores only a hash of it, so it can’t be shown again, and there’s no way to bring this command back for an executor later. If you lose it, you’ll need to rotate the key and rebuild the command by hand. Paste it somewhere safe — your secret manager, your deployment repo — before clicking Done.

Pick an install method

The step opens with the warning “Copy your API key now — it won’t be shown again!”, the key itself with a copy button, and then Choose your installation method.

Each tab contains a complete, ready-to-run command with your gateway URL, your key, and the labels, concurrency and timeout you entered in step 1 already filled in. Pick whichever suits your host — they all produce the same executor.

Step 3 of the wizard showing the API key warning, the key, and the installation method tabs

Docker

The simplest option, and the one to use if you have no particular preference. Pull the official image from Docker Hub and run it:


docker run -d \
  --name qremotex \
  -e QRAPTOR_GATEWAY_URL=wss://exec-{projectShortId}.qraptor.app/ws/executor \
  -e QRAPTOR_API_KEY=qrx_prod_… \
  -e CONCURRENCY=6 \
  -e EXEC_TIMEOUT_SEC=420 \
  -e LABELS='{"env":"prod","region":"us-east-2"}' \
  qraptor/qremotex:latest

CONCURRENCY, EXEC_TIMEOUT_SEC and LABELS carry the values you entered in step 1. LABELS only appears if you added any.

If your scripts need Python packages that aren’t in the base image, pass them in and they’ll be installed at startup:


  -e QRAPTOR_EXTRA_PACKAGES="pandas torch boto3"

For anything beyond a couple of packages, build your own image instead — see the Custom tab below.

The Docker tab showing the generated docker run command with the gateway URL, API key and executor configuration

pip

Installs into an existing Python environment. Requires Python 3.13 or newer.


pip install qremotex
 
export QRAPTOR_GATEWAY_URL=wss://exec-{projectShortId}.qraptor.app/ws/executor
export QRAPTOR_API_KEY=qrx_prod_…
export CONCURRENCY=6
export EXEC_TIMEOUT_SEC=420
export LABELS='{"env":"prod","region":"us-east-2"}'
qremotex

Any packages your scripts import can be installed into the same environment with a normal pip install.

This runs in the foreground. For a long-lived executor, wrap it in systemd or a process manager so it restarts with the host.

Helm

For running the executor as a pod in your own Kubernetes cluster:


# Create secret for API key
kubectl create secret generic qremotex-api-key \
  --from-literal=api-key=qrx_prod_…
 
# Install chart
helm install qremotex \
  oci://registry-1.docker.io/qraptor/qremotex \
  --set config.gatewayUrl=wss://exec-{projectShortId}.qraptor.app/ws/executor \
  --set config.concurrency=6 \
  --set config.execTimeoutSec=420 \
  --set-string config.labels='{"env":"prod"\,"region":"us-east-2"}' \
  --set secrets.existingSecret=qremotex-api-key

The API key goes into a Kubernetes secret rather than onto the command line. Note the escaped comma in config.labels — Helm’s --set parser treats commas as value separators, so the generated command escapes them for you.

Custom image

The right answer for production when your scripts have real dependencies. Extend the base image so packages are baked in rather than installed on every start:


# Dockerfile
FROM qraptor/qremotex:latest
RUN pip install --no-cache-dir pandas torch boto3

Then build and run it with the same environment variables:


docker build -t my-qremotex .
docker run -d \
  -e QRAPTOR_GATEWAY_URL=wss://exec-{projectShortId}.qraptor.app/ws/executor \
  -e QRAPTOR_API_KEY=qrx_prod_… \
  my-qremotex

Confirm it connected

Click Done to return to the executor list. Within a few seconds the executor should flip from Not yet connected to Online, and its card should fill in with the concurrency you set and a recent heartbeat.

Open it to check the details reported by the agent itself — System Info (OS, architecture, Python version, memory, CPU cores), Labels, and Capabilities. If those match the host you started it on, the connection is working end to end.

The executor list showing the new executor as Online with its labels and concurrency

💡

Nothing appeared? Look at the agent’s own logs first — docker logs qremotex. Since every rejection now names its cause and tells you what to do about it, that log line is almost always the fastest answer. Troubleshooting has the full list.

Environment variables

The wizard fills in what most people need. These are the rest, for when you’re writing your own deployment manifest.

Variable	Default	What it does
`QRAPTOR_GATEWAY_URL`	—	Required. Your project’s `wss://exec-…/ws/executor` address.
`QRAPTOR_API_KEY`	—	Required. The key from step 2.
`QRAPTOR_EXECUTOR_NAME`	the hostname	Only used when an executor connects without having been created in Studio first. If you named it in the wizard, that name wins.
`CONCURRENCY`	`25`	Jobs run in parallel.
`EXEC_TIMEOUT_SEC`	`300`	Per-job time limit.
`LABELS`	`{}`	JSON object of tags, e.g. `{"region":"us-east-1","gpu":"true"}`.
`HEARTBEAT_SEC`	`20`	How often the executor reports in.
`RECONNECT_MAX_SEC`	`60`	Ceiling on the reconnect backoff.
`MAX_SCRIPT_SIZE_KB`	`512`	Largest script the executor will accept.
`MAX_MEMORY_MB`	`2048`	Memory ceiling per execution.
`LOG_LEVEL`	`INFO`	Standard Python log levels.
`QRAPTOR_EXTRA_PACKAGES`	—	Space-separated packages installed at container startup.
`ENABLE_SYSTEM_TOOLS`	`true`	Allow qRaptor’s built-in tools to run here.
`ENABLE_USER_TOOLS`	`true`	Allow your project’s own tools to run here.
`ALLOWED_TOOL_KEYS`	`*`	Comma-separated allowlist of tool keys.
`BLOCKED_TOOL_KEYS`	—	Comma-separated blocklist.
`QRAPTOR_API_KEY_FILE`	—	Path to a file holding the key, so it can be reloaded without a restart.

The last four are worth a look if you want to restrict what this executor is willing to run — see Security & networking.

Common issues

It stays on Not yet connected — the agent isn’t reaching the gateway. Check its logs; the message will name the cause.
You just activated the gateway and it’s being refused — the activation check is cached for about five minutes. It clears on its own and the agent keeps retrying.
You lost the command — rotate the key on the API Keys page to get a new one, then rebuild the command using the table above.

Run work on an executor — send a code node or a tool to it.