QuoxAgent

A per-host daemon for fleet management.

QuoxAgent is a lightweight Go daemon that runs on each host you want to manage. It provides secure remote command execution, real-time health monitoring, and AI session tracking, all reporting back to a central Collector service.

What It Is

QuoxAgent is a single binary that installs on a target host as a systemd service. Once running, it:

• Sends heartbeats to the Collector every 30 seconds with CPU, memory, disk, and network metrics
• Accepts command execution requests via its local API (port 9847)
• Tracks AI agent sessions running on the host (Claude Code, Aider, Ollama, etc.)
• Logs every operation to a local audit trail with AEE envelope formatting

The Collector service (port 9848) runs as part of QuoxCORE's Docker Compose stack and aggregates data from all agents across the fleet.

The Problem

Managing distributed infrastructure means juggling SSH sessions, monitoring dashboards, and deployment scripts across dozens or hundreds of hosts. Common pain points:

• No real-time fleet view — You check hosts one at a time via SSH
• Blind spots — A host goes down and nobody notices until a user reports it
• Manual command execution — Running the same command on 20 hosts means writing a loop or Ansible playbook
• No AI visibility — Claude Code sessions running on developer machines are invisible to the team
• Audit gaps — Remote commands executed via SSH leave no centralised record

QuoxAgent solves these by placing a small daemon on each host that maintains a persistent connection to the central platform.

Who It's For

Core Capabilities

Fleet Health Monitoring

Every 30 seconds, each agent pushes metrics to the Collector:

• CPU — Current usage percentage
• Memory — Used, available, total
• Disk — Usage per mount point
• Network — Interface status
• System — OS, kernel, architecture, boot time, uptime

The dashboard displays these as real-time cards with status indicators:

• Green (connected) — Heartbeat received within 90 seconds
• Orange (stale) — No heartbeat for 90+ seconds
• Red (dead) — No heartbeat for 5+ minutes

Remote Command Execution

Execute shell commands on any connected host through the dashboard or API:

# Via the Collector API
curl -X POST http://collector:9848/api/v1/agents/nw-web-01/exec \
  -H "Authorization: Bearer <token>" \
  -d '{"command": "df -h", "timeout": 30}'

Commands run with full audit logging. Every execution creates an AEE envelope recording who ran what, when, on which host, with the complete output and exit code.

Safety gates are enforced via DEFCON levels:

• quoxagent.status — GREEN (read-only, no approval needed)
• quoxagent.logs — GREEN (read-only)
• quoxagent.execute — AMBER (requires approval for sensitive commands)
• quoxagent.install — AMBER (requires approval)

Universal Agent Monitor (UAM)

QuoxAgent tracks AI agent sessions running on the host. This provides fleet-wide visibility into:

Events tracked:

• Session start and end
• Messages (user and agent)
• Tool calls and results
• File changes
• Code execution
• Token usage and cost

Access via the Agent Stream view in QuoxCORE, which shows a real-time feed of all AI activity across the fleet with WebSocket streaming and live filtering.

Plugin System

QuoxAgent supports plugins that extend its capabilities. Plugins are loaded from /opt/quoxagent/tools/ and registered via the local API.

License System

QuoxAgent fleet management is available as a premium plugin (quoxagent-fleet) in QuoxCORE. License validation uses Ed25519 signatures and works offline after initial activation.

Architecture

┌──────────────────────────────────────────┐
│              QuoxCORE Dashboard           │
│         AgentFleetPanel + AgentStream     │
└──────────────┬───────────────────────────┘
               │ HTTP + WebSocket
               ▼
┌──────────────────────────────────────────┐
│         Collector Service (port 9848)     │
│  - Aggregates heartbeats                 │
│  - Routes commands                       │
│  - Stores AEE envelopes (SQLite)         │
│  - Serves install script + binary        │
│  - WebSocket event streaming             │
└──────┬──────────┬──────────┬─────────────┘
       │          │          │
  Heartbeat   Heartbeat   Heartbeat
  (30s push)  (30s push)  (30s push)
       │          │          │
       ▼          ▼          ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ nw-web-01 │ │ nw-db-01 │ │  nw-hv-01   │
│ :9847    │ │ :9847    │ │ :9847    │
│ QuoxAgent│ │ QuoxAgent│ │ QuoxAgent│
└──────────┘ └──────────┘ └──────────┘

Ports

Collector Endpoints

Agent Endpoints (per host)

How It Connects

With QuoxCORE

QuoxAgent is deeply integrated with QuoxCORE:

• The Collector runs as a Docker container in the QuoxCORE stack
• The AgentFleetPanel displays real-time status of all agents
• The AgentStreamView shows live AI session activity
• The MHAInstallPrompt detects when you mention a host without an agent and offers to install one
• AI agents (NOVA, CIPHER) can execute commands on hosts via the Collector API

With QuoxBastion

QuoxAgent and QuoxBastion are complementary:

Together: QuoxBastion maintains the canonical host registry and handles fleet-wide SSH commands. QuoxAgent provides continuous real-time monitoring and AI session tracking on each host. QuoxCORE orchestrates both.

Installation

One-Line Install

From the Collector service:

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

This downloads the binary, creates the config, installs the systemd service, and starts the agent. Heartbeats begin immediately.

Options

--host-id ID        Host identifier (default: hostname)
--collector URL     Collector URL (default: http://10.20.0.126:9848)
--port PORT         Agent API port (default: 9847)
--version VER       QuoxAgent version to install
--uninstall         Remove QuoxAgent from this host

What Gets Installed

• Binary: /opt/quoxagent/bin/quoxagent
• Config: /etc/quoxagent/quoxagent.yaml
• Data: /var/lib/quoxagent/
• Audit: /var/lib/quoxagent/audit/
• Service: /etc/systemd/system/quoxagent.service

Verify

# Check service status
systemctl status quoxagent

# Check local API
curl -s http://localhost:9847/api/v1/status

# Check license
curl -s http://localhost:9847/api/v1/license

Dashboard-Driven Deployment

QuoxCORE can deploy QuoxAgent to hosts automatically:

1. Mention a host in a command ("check disk on nw-web-01")
2. If QuoxAgent isn't installed, the dashboard shows an install prompt
3. Select hosts and confirm
4. QuoxCORE deploys via SSH through the bastion

Configuration

/etc/quoxagent/quoxagent.yaml:

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

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

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

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

Technical Details

Next Steps

• QuoxCORE — The AI command center that orchestrates QuoxAgent
• QuoxBastion — Fleet management via your bastion host
• Quickstart — Get QuoxCORE running (Collector included)
• AI Agents — The specialist agents that use QuoxAgent for execution