# qRemoteX — Federated Remote Execution Agent

Lightweight agent that connects to the [qRaptor](https://qraptor.ai) Executor Gateway via WebSocket (QRP protocol) and
executes Python scripts and tools on your infrastructure — on-prem, VPC, GPU clusters, or edge.

## Install

> **Gateway URL:** Your project's gateway URL is shown in the Studio UI setup wizard.
> Format: `wss://exec-{shortId}.qraptor.app/ws/executor`

### Docker (Recommended)

```bash
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)

```bash
pip install qremotex
```

### Kubernetes (Helm)

```bash
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_...
```

## Run

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

qremotex
```

Or with `python -m`:

```bash
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:

```bash
# 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 [qRemoteX Documentation](https://qraptor.ai/docs/qremotex) 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

```bash
pip install qremotex[dev]
pytest tests/ -v
```

## Requirements

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

## Architecture

```
┌─────────────┐    QRP/WebSocket     ┌──────────────────┐     API      ┌──────────────┐
│  qRemoteX   │◄──────────────────►│  qRaptor Gateway  │◄───────────►│  qRaptor     │
│  (Agent)    │   Heartbeat, Jobs   │  (Edge Router)    │             │  Studio UI   │
│             │   Results, Traces   │                   │             │              │
└──────┬──────┘                     └──────────────────┘             └──────────────┘
       │
       ▼
  Your Infrastructure
  (DB, APIs, GPU, Files)
```

**How it works:**
1. qRemoteX connects to the qRaptor Gateway via secure WebSocket
2. The gateway dispatches jobs (Python scripts, tool calls) to the agent
3. The agent executes locally on your infrastructure and streams results back
4. All communication is encrypted (TLS) and authenticated (API key + HMAC)

Learn more at [qraptor.ai](https://qraptor.ai)

## License

Proprietary — Copyright © 2026 [AugmentAppz](https://augmentappz.ai). All rights reserved.

Contact: [innovate@augmentappz.ai](mailto:innovate@augmentappz.ai)