# Extending qRemoteX — Installing Additional Packages

qRemoteX ships with core dependencies only. You can install additional Python packages
to support your agents' tools (e.g., `pandas` for data processing, `boto3` for AWS access).

---

## 1. Docker — Environment Variable (Quick Start)

Pass package names via `QRAPTOR_EXTRA_PACKAGES`. Packages install at container startup.

```bash
docker run -d \
  --name qremotex \
  -e QRAPTOR_GATEWAY_URL=wss://exec-{shortId}.qraptor.app/ws/executor \
  -e QRAPTOR_API_KEY=qrx_prod_... \
  -e QRAPTOR_EXTRA_PACKAGES="pandas torch boto3" \
  qraptor/qremotex:latest
```

**Pros:** Zero files, zero Docker knowledge required.
**Cons:** Installs on every container start (slower startup), no version pinning.

---

## 2. Docker — Mounted Requirements File

Mount a `requirements.txt` to `/app/extra-requirements.txt` for version-pinned installs.

```bash
# Create a requirements file on the host
cat > /opt/qremotex/extra-requirements.txt << 'EOF'
pandas==2.2.0
torch==2.3.0
boto3>=1.34
EOF

docker run -d \
  --name qremotex \
  -v /opt/qremotex/extra-requirements.txt:/app/extra-requirements.txt:ro \
  -e QRAPTOR_GATEWAY_URL=wss://exec-{shortId}.qraptor.app/ws/executor \
  -e QRAPTOR_API_KEY=qrx_prod_... \
  qraptor/qremotex:latest
```

**Pros:** Version pinning, reproducible, easy to update.
**Cons:** Installs on every container start.

---

## 3. Docker — Custom Image (Recommended for Production)

Build your own image extending the official base. Packages are baked in — fast startup.

```dockerfile
# Dockerfile.custom
FROM qraptor/qremotex:latest

# Install your packages (runs as root during build, then drops back to qremotex user)
USER root
RUN pip install --no-cache-dir \
    pandas==2.2.0 \
    torch==2.3.0 \
    boto3>=1.34 \
    my-internal-lib==0.5.0
USER qremotex
```

```bash
docker build -t my-company/qremotex-custom:latest -f Dockerfile.custom .

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

**Pros:** Fast startup, reproducible, version-pinned, CI/CD friendly.
**Cons:** Must rebuild when upgrading qRemoteX base image.

---

## 4. pip Install — Native Python

Install qRemoteX and your packages in the same virtual environment.

```bash
# Create a venv (recommended)
python3.13 -m venv qremotex-env
source qremotex-env/bin/activate

# Install qRemoteX + your packages
pip install qremotex pandas torch boto3

# Configure and run
export QRAPTOR_GATEWAY_URL=wss://exec-{shortId}.qraptor.app/ws/executor
export QRAPTOR_API_KEY=qrx_prod_...
qremotex
```

**Pros:** Most flexible, familiar Python workflow.
**Cons:** No container isolation; you manage the Python environment.

---

## 5. Kubernetes — Helm with Custom Image

Use the official Helm chart with your custom Docker image.

```yaml
# custom-values.yaml
image:
  repository: my-company/qremotex-custom
  tag: "2.0.0"

config:
  gatewayUrl: "wss://exec-{shortId}.qraptor.app/ws/executor"

secrets:
  existingSecret: "qremotex-api-key"
```

```bash
# Create the API key secret
kubectl create secret generic qremotex-api-key \
  --from-literal=api-key=qrx_prod_...

# Install with custom values
helm install qremotex oci://registry-1.docker.io/qraptor/qremotex \
  -f custom-values.yaml
```

---

## 6. Kubernetes — Init Container Pattern

Install extra packages in an init container without building a custom image.

```yaml
# init-container-values.yaml
initContainers:
  - name: install-packages
    image: qraptor/qremotex:latest
    command: ["pip", "install", "--user", "pandas", "torch", "boto3"]
    volumeMounts:
      - name: user-packages
        mountPath: /app/.local

extraVolumeMounts:
  - name: user-packages
    mountPath: /app/.local

extraVolumes:
  - name: user-packages
    emptyDir: {}
```

---

## 7. Common Packages for Agent Tools

| Category | Packages |
|----------|----------|
| **Data** | `pandas`, `numpy`, `polars`, `openpyxl` |
| **ML/AI** | `torch`, `transformers`, `openai`, `anthropic`, `langchain` |
| **Database** | `asyncpg`, `sqlalchemy`, `pymongo`, `redis` |
| **Cloud** | `boto3`, `azure-storage-blob`, `google-cloud-storage` |
| **HTTP** | `httpx`, `requests`, `aiohttp` (already included) |
| **Parsing** | `beautifulsoup4` (included with `[tools]`), `lxml`, `PyPDF2` |

---

## 8. Troubleshooting

### Packages fail to install at startup

Check container logs for pip errors:

```bash
docker logs qremotex
```

Common causes:
- **Network issues:** Container can't reach PyPI. Check DNS/proxy settings.
- **Typos:** Verify package names in `QRAPTOR_EXTRA_PACKAGES` or requirements file.
- **Version conflicts:** Pin compatible versions in a requirements file.

### Binary packages on ARM64

Some packages (e.g., `torch`) don't publish ARM64 wheels. Options:
- Use the `linux/amd64` image platform: `docker run --platform linux/amd64 ...`
- Install from source (slower): add build tools to your custom image
- Check package docs for ARM64 support

### Package version conflicts with qRemoteX core

qRemoteX core depends on `aiohttp>=3.9`, `psutil>=5.9`, and `pydantic>=2.0`.
If your packages conflict, pin compatible versions in a requirements file.
