Metadata-Version: 2.4
Name: qremotex
Version: 2.0.11590
Summary: qRemoteX — Federated Remote Execution Agent for qRaptor
Project-URL: Homepage, https://qraptor.ai
Project-URL: Documentation, https://docs.qraptor.ai/qremotex
Author-email: qRaptor Engineering <engineering@qraptor.ai>
License: Proprietary
Keywords: agent,federated,qraptor,remote-execution
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.13
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: psutil<7,>=5.9
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: tools
Requires-Dist: asyncpg>=0.29; extra == 'tools'
Requires-Dist: beautifulsoup4>=4.12; extra == 'tools'
Requires-Dist: httpx>=0.27; extra == 'tools'
Description-Content-Type: text/markdown

# 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)

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

## Quick Start (Development)

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

```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 [docs/EXTENDING_QREMOTEX.md](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

```bash
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](docs/QREMOTEX_ARCHITECTURE_AND_IMPLEMENTATION_PLAN.md) for full design.