ai-context/jarvis.md

# JARVIS System Reference Card

## Access
- **Dashboard:** https://jarvis.orbishosting.com (login: myron / Joker1974!!!)
- **Admin portal:** https://jarvis.orbishosting.com/admin (same login)
- **DB:** `jarvis_db` on DO localhost — user: `jarvis_user` / `J4rv1s_Pr0t0c0l_2026!`
- **phpMyAdmin:** https://jarvis.orbishosting.com/phpmyadmin (myron / Joker1974!!!)
- **GitHub repo:** myronblair/jarvis (auto-deploy on push to main)

## File Structure (on DO at /home/jarvis.orbishosting.com/)
```
public_html/
  index.html          — main Iron Man HUD (all UI)
  api.php             — API router
  admin/index.php     — admin portal (single PHP+JS file)
  agent/              — agent installers
api/
  config.php          — all credentials/constants (gitignored)
  lib/db.php          — JarvisDB class (query/execute/single/insert)
  lib/kb_engine.php   — KBEngine intent matching
  endpoints/
    agent.php         — agent registration/heartbeat/metrics/commands
    chat.php          — 4-tier chat: KB→action intents→Ollama→Groq→Claude
    network.php       — network device list + scan endpoint
    netscan.php       — push endpoint for PVE1 nmap results (no auth needed)
    do_server.php     — reads /proc directly (no SSH loopback)
    stats_cache.php   — every 5min cron: Proxmox cluster API, HA, weather, news
    facts_collector.php — every 3min cron: system stats, site health
    system.php        — local system metrics (services: lshttpd,mysql,redis,memcached,postfix,dovecot,jarvis-agent)
    alerts.php        — alert CRUD + auto-generate
    news.php          — serves api_cache['news'] + custom kb_facts(category='custom_news')
```

## Agent System
- **Registration key:** `f846a9aaf7ce9a61742c63c87c4186052a71d2a580c65518`
- **Install one-liner (Linux):** `curl -sk https://jarvis.orbishosting.com/install-agent.sh | bash -s <hostname> <linux|proxmox>`
- **For VMs (need sudo):** `curl -sk https://jarvis.orbishosting.com/install-agent.sh > /tmp/i.sh && echo "Joker1974!" | sudo -S bash /tmp/i.sh <hostname> linux`
- **Agent config:** `/etc/jarvis-agent/config.json` — runtime state at `/var/lib/jarvis-agent/state.json`
- **If agent gets 401 "Invalid agent key":** state.json has stale key — overwrite with correct agent_id + api_key from DB
- **Heartbeat:** every 10s | **Metrics:** every 30s | **Commands:** polled on heartbeat
- **Shell commands:** send via agent_commands table with `{"command":"/path/to/script","allowed":true}`

## Currently Online Agents
| agent_id | hostname | IP | type |
|----------|----------|----|------|
| jarvis-do_orbis.or | jarvis-do | 165.22.1.228 | linux |
| claude_pve | claude | 10.48.200.90 | proxmox |
| pve2_e147a8bc | pve2 | 10.48.200.91 | proxmox |
| networkbackup_NetworkB | networkbackup | 10.48.200.99 | linux |
| homeassistant_ha | homeassistant | 10.48.200.97 | homeassistant |
| homebridge_b57cbaea | homebridge | 10.48.200.18 | linux |
| alien-pc_windows | alien-pc | 10.48.200.66 | linux |

**Pending:** jellyfin (10.48.200.33), ollama-ai (10.48.200.95)

## Network Scanning
- PVE1 cron: `*/3 * * * * /usr/local/bin/jarvis-netscan.sh`
- Script runs nmap, parses output, POSTs JSON to `https://165.22.1.228/api/netscan` with `X-Registration-Key` header
- Scan Now button in admin queues shell command to PVE1 agent (picks up within 10s)

## Chat Architecture
```
Tier 0:   HA entity control (fuzzy match → call HA API)
Tier 0.5: Network device management
Tier 1:   KB intent engine (response type → instant reply)
Tier 1b:  Action intents (network_scan → DB data + queue PVE1 scan)
Tier 2:   Ollama llama3.2 at http://10.48.200.95:11434 (5s timeout)
Tier 3:   Groq compound-beta-mini (cloud, fast)
Tier 4:   Claude API fallback
```
- Groq model name: `compound-beta-mini` (NOT `groq/compound-beta-mini`)
- network_scan intent: action type — must be handled in Tier 1b or Groq will fabricate

## DB Key Tables
```sql
registered_agents    — agent_id, hostname, agent_type, ip_address, api_key, status, last_seen
agent_metrics        — agent_id, metric_type, metric_data(JSON), recorded_at
  -- Extract: JSON_EXTRACT(metric_data,'$.cpu_percent'), JSON_EXTRACT(metric_data,'$.memory.percent')
  -- NO cpu_pct/mem_pct columns — always use JSON_EXTRACT
agent_commands       — agent_id, command_type, command_data(JSON), status(pending/delivered)
network_devices      — ip, mac, hostname, alias, device_type, status, last_seen
alerts               — alert_type, title, message, severity, resolved
kb_facts             — category, fact_key, fact_value (custom_news category for pinned news)
kb_intents           — intent_name, pattern(regex), response_template, action_type, priority, active
api_cache            — cache_key(proxmox/news/weather/ha_entities), data(JSON), updated_at
```

## Proxmox Cache
- `stats_cache.php` uses cluster API at `orbisne.fortiddns.com:8006` (NOT PROXMOX_HOST local IP)
- Returns all VMs from both PVE1 and PVE2 via `/cluster/resources?type=vm`
- Cache key: `proxmox` in api_cache table

## Cron Jobs (on DO)
```
*/3 * * * *  /usr/local/lsws/lsphp85/bin/lsphp .../facts_collector.php
*/5 * * * *  /usr/local/lsws/lsphp85/bin/lsphp .../stats_cache.php
0 2 * * *    /usr/local/bin/jarvis-backup.sh
```
**Cron on PVE1:**
```
*/3 * * * *  /usr/local/bin/jarvis-netscan.sh
```

## Backups
- Script: `/usr/local/bin/jarvis-backup.sh`
- Output: `/var/backups/jarvis/jarvis_backup_YYYY-MM-DD_HH-MM-SS.tar.gz`
- Contains: all public_html dirs + SQL dumps of 6 DBs
- Downloadable from: admin portal → BACKUPS tab
- Retention: 7 days

## API Auth
- Main JARVIS API: session token via `X-Session-Token` header (or PHP session)
- Agent endpoints: `X-Agent-Key` header (per-agent key from registered_agents.api_key)
- Netscan endpoint: `X-Registration-Key` header (shared registration key)
- Admin portal: separate PHP session (`session_name('jarvis_admin')`)
- Cloudflare passes real client IP in `CF-Connecting-IP` header