qremotex 2.0.11590

qRemoteX — Federated Remote Execution Agent for qRaptor

qRemoteX — Federated Remote Execution Agent

Lightweight agent that connects to the qRaptor Executor Gateway via WebSocket (QRP protocol) and executes Python scripts and tools on customer infrastructure — on-prem, VPC, GPU clusters, or edge.

Install

Docker (Recommended)

docker run -d \
  --name qremotex \
  -e QRAPTOR_GATEWAY_URL=wss://exec-{shortId}.qraptor.app/ws/executor \
  -e QRAPTOR_API_KEY=qrx_prod_... \
  qraptor/qremotex:latest

pip (PyPI)

pip install qremotex

Kubernetes (Helm)

helm install qremotex oci://registry-1.docker.io/qraptor/qremotex \
  --set config.gatewayUrl=wss://exec-{shortId}.qraptor.app/ws/executor \
  --set secrets.apiKey=qrx_prod_...

Quick Start (Development)

# Install from source (core only)
pip install -e .

# Install with built-in tool handlers (db_query, http_request, file_parse, web_crawler)
pip install -e ".[tools]"

# Install dev dependencies (pytest, ruff)
pip install -e ".[dev]"

Run

export QRAPTOR_GATEWAY_URL="wss://exec-{shortId}.qraptor.app/ws/executor"
export QRAPTOR_API_KEY="qrx_prod_..."

qremotex

Or with python -m:

python -m qremotex.main

Configuration (Environment Variables)

Variable	Required	Default	Description
QRAPTOR_GATEWAY_URL	Yes	—	WebSocket URL (wss://...)
QRAPTOR_API_KEY	Yes	—	API key (qrx_{env}_{secret})
QRAPTOR_EXECUTOR_ID	No	auto (uuid4)	Stable executor ID
QRAPTOR_EXECUTOR_NAME	No	hostname	Display name
CONCURRENCY	No	25	Max parallel jobs
HEARTBEAT_SEC	No	20	Heartbeat interval (seconds)
EXEC_TIMEOUT_SEC	No	300	Default execution timeout
MAX_SCRIPT_SIZE_KB	No	512	Max script size (KB)
MAX_MEMORY_MB	No	2048	Memory limit per execution
LABELS	No	{}	JSON labels for routing ({"region":"us-east-1","gpu":"true"})
LOG_LEVEL	No	INFO	Logging level
QRAPTOR_API_KEY_FILE	No	—	Path to key file for hot-reload (SIGHUP)
QRAPTOR_EXTRA_PACKAGES	No	—	Space-separated pip packages to install at startup (Docker only)

Installing Extra Packages

qRemoteX ships with core dependencies only. Add packages your agents need:

# Docker: inline packages
docker run -d \
  -e QRAPTOR_EXTRA_PACKAGES="pandas torch boto3" \
  -e QRAPTOR_GATEWAY_URL=wss://... \
  -e QRAPTOR_API_KEY=qrx_prod_... \
  qraptor/qremotex:latest

# Docker: custom image (recommended for production)
# Dockerfile:
#   FROM qraptor/qremotex:latest
#   USER root
#   RUN pip install --no-cache-dir pandas torch boto3
#   USER qremotex

# pip: install alongside qremotex
pip install qremotex pandas torch boto3

See docs/EXTENDING_QREMOTEX.md for all installation patterns.

Deployment Options

Method	Best For	Registry
Docker	Production, easy setup	Docker Hub: qraptor/qremotex
pip	Dev/testing, native Python	PyPI: pip install qremotex
Helm	Kubernetes clusters	OCI: oci://registry-1.docker.io/qraptor/qremotex
Binary	Air-gapped, no Python/Docker	Download from Studio UI

Key Rotation

Rotate keys without restart:

1. Set QRAPTOR_API_KEY_FILE=/path/to/key.txt
2. Write the new key to the file
3. Send kill -HUP <pid> to the agent process

Tests

pip install -e ".[dev]"
pytest tests/ -v

Requirements

• Python 3.13+ (for pip install)
• Docker (for container deployment)
• A qRaptor account with an active subscription

Architecture

See docs/QREMOTEX_ARCHITECTURE_AND_IMPLEMENTATION_PLAN.md for full design.