File size: 6,937 Bytes
a9876bc fce80d1 a9876bc 181b8c1 a9876bc 181b8c1 fce80d1 181b8c1 a9876bc | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 | # mona-agent Architecture
How the open-source device daemon is built, and how it talks to the
mona.expert cloud.
## Overview
mona-agent is a **headless Node.js daemon** with two jobs:
1. **Execute** — run local tools (files, shell, network, system info) on
behalf of the cloud agent.
2. **Report** — stream device metrics and command results back to the cloud
in real time.
```
┌─────────────────────────────────────┐ ┌──────────────────────────────┐
│ Device (your machine) │ │ mona.expert cloud (SaaS) │
│ │ │ │
│ mona-agent │ │ Control plane API │
│ ┌──────────────┐ ┌────────────┐ │ │ /api/v1/agent/verify │
│ │ ControlChannel│◄─►│ tools/ │ │ │ /api/v1/agent/stats │
│ │ (HTTPS + WS) │ │ files │ │ │ /api/v1/agent/chat … │
│ │ │ │ shell │ │ │ │
│ │ metrics │ │ net │ │ │ AI engine (the brain) │
│ │ commands │ │ sysinfo │ │ │ Dashboard + device overview │
│ └──────────────┘ └────────────┘ │ │ Key vault (AES-256) │
│ │ │ │ Audit log │
│ ▼ │ └──────────────────────────────┘
│ TUI (mona-agent gui) │
│ headless daemon (mona-agent start) │
└─────────────────────────────────────┘
```
## Modules
| Module | Responsibility |
|---|---|
| `bin/mona-agent.js` | CLI entrypoint — `gui`, `start`, `login`, `connect`, `chat`, `exec` |
| `src/config.js` | Credentials, cloud endpoint resolution, platform detection |
| `src/cloud.js` | REST client for the control plane API (Bearer-auth) |
| `src/control.js` | Control channel: registration, command dispatch, metrics streaming |
| `src/api.js` | Local HTTP API + WebSocket (used by the local dashboard / desktop UI) |
| `src/tools/*` | The tool sandbox: `files`, `shell`, `net`, `sysinfo` |
| `src/tui.js` | Terminal dashboard — live log, scrollback, status bar |
| `src/log.js` | Structured logging (quiet in daemon mode) |
## Control channel lifecycle
1. **Boot** — `config.js` loads `~/.mona-agent/credentials.json` and
resolves the cloud endpoint (`MONA_CLOUD` or `https://agent.mona.expert`).
2. **Verify** — the daemon authenticates with `POST /api/v1/agent/verify`
(Bearer token). The server returns the agent identity and capabilities.
3. **Metrics** — every 10 seconds the daemon POSTs a snapshot to
`/api/v1/agent/stats`: CPU %, load average, memory, disk, uptime, host
and platform info.
4. **Commands** — on the Sngine control plane the device **polls the cloud
task queue** every 2 s (`GET /api/v1/agent/tasks`, claim, then report
via `POST /api/v1/agent/tasks/:id/result`). No inbound port, no
WebSocket upgrade required. On the Docker platform, commands arrive
over the WebSocket control channel instead.
5. **Resilience** — metrics streaming is independent of the WebSocket
channel. If the server cannot upgrade to WebSocket (e.g. shared hosting
behind LiteSpeed), the daemon transparently falls back to HTTPS polling
and keeps streaming — no reconnect storm.
## Agentic execution loop
Every task runs the same loop, wherever it came from (dashboard chat,
CLI, or the cloud queue):
```
┌───────────────────────────────────────────────────┐
│ mona.expert brain │
│ reason answer in text OR emit one tool call │
└───────────────┬───────────────────────▲──────────┘
task (HTTPS) │ │ tool result
┌───────────────▼───────────────────────┴──────────┐
│ mona-agent │
│ execute tool locally (sysinfo|shell|files|net) │
└───────────────────────────────────────────────────┘
```
- Up to **8 tool steps per task** — the loop ends when the brain answers
in plain text.
- Tool protocol is provider-agnostic: the brain replies with a single
JSON object `{"tool":"<name>","args":{...}}` or plain text. No
provider-specific function-calling plumbing.
- Every step is reported to the cloud (`tool.call` / `tool.result`) and
appears live in the dashboard activity feed.
- The final answer is stored in the cloud conversation — history survives
restarts and is visible from every client.
## Metrics pipeline (HTTP-first)
The client was designed so that **metrics never depend on a WebSocket
upgrade**:
- Every 10 s: `POST /api/v1/agent/stats` with CPU, memory, disk, load,
uptime, hostname, platform, arch, version, IP.
- The cloud keeps the latest snapshot plus a rolling 180-point history per
device; the dashboard polls every 3 s — effectively live.
- A device is shown as **online** when its last snapshot is ≤ 20 s old.
## Security model (client side)
- **No AI provider keys on the device.** Only a mona.expert device token is
stored (`~/.mona-agent/credentials.json`, mode 0600).
- **Guarded shell** — commands run through an allowlist; dangerous patterns
are blocked before execution.
- **Confined files tool** — reads/writes are limited to safe, allowed paths.
- **Egress-only** — the daemon opens outbound connections only; it listens
on localhost only (for the local dashboard).
See [SECURITY.md](../SECURITY.md) for the full model and disclosure policy.
## Why HTTPS polling instead of WebSockets?
The control plane runs on shared hosting (LiteSpeed), where WebSocket
proxying is not always available and long-running Node processes are not
possible. The client therefore uses:
- **WebSocket** when the server upgrades it (self-hosted / VPS setups),
- **HTTPS polling + streaming metrics** everywhere else.
One code path, two transports — the daemon decides at runtime.
|