QuoxAgent: Your Fleet of Scouts

QuoxAgent places a lightweight scout on each server in your infrastructure. These agents report back continuously, execute commands instantly, and transform your servers into a unified, responsive fleet.

What is QuoxAgent?

QuoxAgent is a lightweight program that runs on each server in your infrastructure, acting as Quox's eyes, ears, and hands on that machine.

Think of it this way: Imagine you are the captain of a large ship, but you cannot be everywhere at once. So you station a trusted crew member on each deck - someone who watches for problems, reports back immediately, and can carry out your orders on the spot. That is what QuoxAgent does for your servers.

Each QuoxAgent is like a scout stationed at an outpost. It is small, quiet, and always ready. When Quox needs information or wants to take action, your scouts are already there, waiting to help.

Why QuoxAgent changes everything

Without QuoxAgent, managing servers is like sending messages by carrier pigeon - you have to establish a new SSH connection each time, wait for authentication, and hope everything works. With QuoxAgent, you have a direct radio link to every machine in your fleet.

Before QuoxAgent

• Open SSH connection (2-3 seconds)
• Authenticate (1-2 seconds)
• Run command
• Close connection
• Repeat for every server, every time

After QuoxAgent

• Quox says "go"
• Scout responds instantly
• Results stream back in real-time

How it works

Here is the architecture in simple terms:

                    Your Browser
                         |
                         v
              +-------------------+
              |    QuoxCORE        |
              +-------------------+
                         |
                         v
              +-------------------+
              |  QuoxAgent Collector |  <-- Central command hub (port 9848)
              |  (Your main host)    |
              +-------------------+
                    /    |    \
           heartbeat  heartbeat  heartbeat
              /         |          \
             v          v           v
      +----------+ +----------+ +----------+
      | QuoxAgent| | QuoxAgent| | QuoxAgent|   <-- Agents on each server
      | nw-web-01 | | nw-db-01 | | nw-monitor-01   |       (port 9847)
      +----------+ +----------+ +----------+

The flow:

1. Scouts check in - Every 30 seconds, each QuoxAgent sends a heartbeat to the Collector: "I am alive, here is my status"
2. Collector tracks everyone - The Collector maintains a live map of all your servers and their health
3. You give commands - When you ask Quox to do something on a server, it talks directly to that server's scout
4. Scouts report back - Results, logs, and metrics flow back instantly through the Collector to your dashboard

Installation: it takes 30 seconds

Installing QuoxAgent on any server is a single command. No packages to install, no dependencies to manage.

Quick install (on any server you want to manage)

curl -sSL http://10.20.0.126:9848/install | sudo bash -s -- --host-id $(hostname)

That is it. The command:

1. Downloads the QuoxAgent binary for your architecture
2. Creates a systemd service
3. Configures the agent with your Collector's address
4. Starts the service immediately

Within seconds, the new server appears in your QuoxCORE dashboard.

Deploy multiple servers from Quox

Already have SSH access configured? Deploy QuoxAgent to multiple hosts at once:

# Check QuoxAgent status on specific hosts
quoxagent-deploy --check nw-monitor-01 nw-edge-gw-01 nw-web-01

# Install QuoxAgent on specific hosts
quoxagent-deploy nw-monitor-01 nw-edge-gw-01

# Install QuoxAgent on ALL known hosts at once
quoxagent-deploy all

# Remove QuoxAgent from a host
quoxagent-deploy --uninstall nw-worker-01

Verify installation

After installing, confirm your scout is reporting in:

# On the server itself
systemctl status quoxagent

# From your Quox host
curl -s http://10.20.0.126:9848/api/v1/agents | jq '.[] | .host_id'

What your scouts can do

Once installed, each QuoxAgent enables:

Real-time health monitoring

Your dashboard shows which servers are healthy, degraded, or offline - updated every 30 seconds without any polling from your side.

Execute commands instantly

Run any command on any server through Quox. No SSH delays, no connection timeouts.

Track AI agent activity

The Universal Agent Monitor (UAM) shows all Claude, GPT, or Ollama sessions running across your fleet in real-time. See what your AI agents are working on, which files they are modifying, and how much they are costing.

Collect metrics

CPU usage, memory, disk space, running processes - all collected and reported automatically.

Troubleshooting

QuoxAgent not appearing in dashboard

Check if the service is running:

systemctl status quoxagent

Check if it can reach the Collector:

curl -v http://10.20.0.126:9848/health

Check the QuoxAgent logs:

journalctl -u quoxagent -f --no-pager

QuoxAgent shows as "stale" or "offline"

This means the Collector has not received a heartbeat recently. Common causes:

• Network issue: The server cannot reach your Collector host
• Firewall blocking port 9848: Ensure outbound connections are allowed
• QuoxAgent service stopped: Run systemctl start quoxagent
• Wrong Collector URL in config: Check /etc/quoxagent/quoxagent.yaml

Permission denied during install

The install script requires sudo to:

• Copy the binary to /usr/local/bin/
• Create the systemd service file
• Set up the /etc/quoxagent/ configuration directory

Run the curl command with sudo as shown in the examples above.

Updating QuoxAgent to a new version

# Stop the service
sudo systemctl stop quoxagent

# Re-run the install (it will replace the binary)
curl -sSL http://10.20.0.126:9848/install | sudo bash -s -- --host-id $(hostname)

# The service auto-starts after install

Fleet power: what you can build

With QuoxAgent deployed across your infrastructure, you gain fleet-wide capabilities:

One command, many servers

"Update nginx configuration on all web servers"

Quox identifies your web servers and executes the update in parallel through each scout.

Fleet-wide health dashboard

See CPU, memory, and disk usage across 50 servers at a glance. Spot the one server running hot before it becomes a problem.

Universal agent monitor

Every AI coding session, every Claude agent, every GPT call - visible in one stream. Know what your AI fleet is doing at all times.

Instant incident response

When something breaks at 2 AM, you do not SSH into 20 servers looking for the problem. Your scouts are already watching, and Quox knows exactly which host is misbehaving.

MHA - Quox Helper Agent

MHA is a per-host sidecar daemon that enables direct command execution, monitoring, and fleet management.

Architecture

Browser → Dashboard → nginx → Collector (9848) → MHA Agents (9847)
                                    ^
                              MHA heartbeats

Project Structure

/home/control/mha/
├── cmd/mha/main.go              # Daemon entry point
├── internal/
│   ├── agent/                   # Lifecycle management
│   ├── heartbeat/               # Heartbeat + metrics collection
│   ├── metrics/                 # Prometheus endpoint
│   └── api/                     # HTTP API server
├── configs/
│   └── mha-push.yaml           # Configuration
├── deploy/
│   ├── install.sh              # Installation script
│   └── deploy-to-host.sh       # Remote deployment script
└── bin/mha                      # Compiled binary

Deployment

Quick Install (on any host)

curl -sSL http://10.20.0.10:9848/install | sudo bash -s -- --host-id $(hostname)

Deploy from Quox

# Check MHA status on hosts
mha-deploy --check nw-monitor-01 nw-edge-gw-01

# Install on specific hosts
mha-deploy nw-monitor-01 nw-edge-gw-01

# Install on all known hosts
mha-deploy all

# Uninstall
mha-deploy --uninstall nw-monitor-01

Dashboard Integration

The dashboard automatically detects hosts mentioned in commands and prompts to install MHA if not present:

• src/components/mha/MHAInstallPrompt.jsx - Install prompt UI
• src/services/mhaClient.js - MHA API client
• src/components/monitoring/AgentFleetPanel.jsx - Fleet status panel

MHA Collector API (port 9848)

MHA Agent API (port 9847)

Configuration

Example /etc/mha/mha.yaml:

agent:
  host_id: "nw-worker-01"
  log_level: info
  data_dir: /var/lib/mha
  tools_dir: /opt/mha/tools

heartbeat:
  interval: 30s
  collector_url: "http://10.20.0.10:9848"
  mode: push
  timeout: 10s

api:
  listen: "0.0.0.0:9847"
  enable_metrics: true

audit:
  enabled: true
  path: /var/lib/mha/audit/audit.log

Universal Agent Monitor (UAM)

The UAM provides real-time visibility into all AI agent sessions running across the fleet.

Dashboard Access

• Command Center view '5' (Agent Stream)
• src/components/agents/AgentStreamView.jsx - Main UI component

CLI Access

mha agent watch                    # Stream all agent events
mha agent watch --host nw-worker-01    # Filter by host
mha agent watch --type cli         # Filter by agent type
mha agent sessions                 # List current sessions

WebSocket Endpoint

GET /ws/agents/events

Query Parameter Filters

• agent_type - cli, api, local, custom (comma-separated)
• host_id - Filter by host (comma-separated)
• session_id - Filter by session (comma-separated)
• event_type - Filter by event type (comma-separated)

Clients can also update filters dynamically by sending JSON:

{"agent_types": ["cli"], "host_ids": ["nw-worker-01"]}

Supported Agent Types

Supported Providers

• anthropic - Claude models
• openai - GPT models
• google - Gemini models
• local - Local models (Ollama, etc.)
• custom - Custom/unknown providers

Event Types

Session Tracking

Each session includes:

• Unique ULID identifier
• Agent classification (type, name, provider, model)
• Project/working directory context
• Lifecycle status and timestamps
• Activity metrics (messages, tools, files)
• Resource usage (tokens, cost)

MHA Implementation Files

• /home/control/mha/internal/api/websocket.go - WebSocket server and EventHub
• /home/control/mha/pkg/agents/types.go - Agent types and session structures
• /home/control/mha/cmd/mha/agent.go - CLI commands