⚡ Gunam

Gunam — A cloud-free, FFI-first Rust agent for on-premises device management. OTA updates, telemetry, panic-safe operation, and offline-first sync.

---

Why Gunam?

Most device management tools assume you want the cloud. Gunam is built for the opposite: on-premises, air-gapped, and edge environments where:

• ❌ Cloud dependencies are unacceptable
• ❌ Network connectivity is unreliable (offline-first)
• ❌ Panics crashing your host application are a dealbreaker
• ❌ A/B rollback and delta updates are required, not nice-to-have

Gunam solves these by being:

• FFI-first — Call from C, Python, Go, Zig, or anything with a C ABI
• Panic-safe — Every FFI entry point catches panics. The host never crashes.
• Cloud-free — SQLite for local sync, MQTT for optional telemetry
• Honest — Every probe returns Available, Unavailable, or Failed. No silent assumptions.

---

Design Principle: Access Tiers

Gunam doesn't assume every device has the same level of control over itself. A device's OS (DeviceClass) and a device's actual write access (AccessTier) are tracked separately — because the same OS can land in different tiers depending on how it's deployed (rooted vs. stock, OEM-flashed vs. sandboxed app).

Tier	What it means	What Gunam can do there
ImageLevel	You flash the OS yourself — real partitions, real bootloader	True A/B slot switching, bootloader-driven auto-rollback
PrivilegedSystem	Root/admin, but stock bootloader	System-level writes, but rollback logic runs in userspace
AppLevel	Sandboxed app, no root (today's default reality)	Old-file/new-file swap, app-level health check + relaunch-on-failure
ReadOnly / Unknown	No write access, or unverified environment	Telemetry and capability reporting only — no update actions attempted

Tiers are detected by probing, not assumed from OS alone, and Gunam degrades gracefully (and logs it) if a device's effective tier changes at runtime. This is foundational architecture as of v0.1 — full implementation lands tier-by-tier starting with AppLevel.

---

Features (v0.1)

Modules

Module	Description	Status
CPU	Load percentage, core count, frequency via /proc/stat	✅ Linux
Memory	Total/used/free RAM, swap usage via /proc/meminfo	✅ Linux
Disk	Total/used/free space, I/O stats via /sys/block	✅ Linux
Battery	Percentage, status (charging/discharging), cycle count via /sys/class/power_supply	✅ Linux
Network	Interface stats, connectivity check (background, non-blocking)	✅ Linux (partial)

Core Capabilities

• Panic Firewall — catch_unwind at every FFI boundary
• Polling Strategies — Constant, Interval(Duration), OnEvent, OnDemand
• Access Tier Model — DeviceClass + AccessTier tracked independently, probed at runtime (see above)
• OTA State Machine — Idle → Downloading → Verified → Applying → Active | RollingBack → Idle (persisted)
• Sync Buffer — SQLite-backed queue, events deleted only after server ACK
• Capability Report — Printed at startup, queryable via agent.has_capability("battery")
• Platform Detection — DeviceClass enum (Linux first, Android/Windows planned)

---

Roadmap

Next — v0.2–v0.5 (Months 2–6)

Feature	Status
OTA at AppLevel tier (signed binary swap + health-check relaunch)	🚧 Planned
Android platform support	🚧 Planned
Windows platform support	🚧 Planned
MQTT message queue	🚧 Planned
Delta updates (bsdiff/bspatch)	🚧 Planned
Event-type sensors	🚧 Planned

Later — v1.x (Year 1)

• PrivilegedSystem and ImageLevel OTA tiers (real A/B partitions, dm-verity, bootloader-driven rollback)
• WebSocket dashboard layer
• Air-gapped update support (IPSec/WiFi Direct)
• Stream-type inputs (camera, radar, audio)
• Rule-based device health scoring

Exploratory — v2.x–v3.x

• Custom storage engine
• ML-based health scoring
• Scoped MDM-style permission model
• ML model integration hooks

📖 Full details: ROADMAP.md

---

Quick Start

Add to Cargo.toml

[dependencies]
gunam = "0.1.0"