NAVIG Mini

Lightweight autonomous agent for low-power devices: Raspberry Pi, NAS, VPS, embedded Linux.

Zero mandatory dependencies — runs on any Python 3.6+ with only the stdlib.

Repository Structure

navig-mini/
├── agent.py          # HTTP daemon (port 9191): /ping /stats /run /
├── monitor.py        # Cron-based Telegram alert monitor
├── install.sh        # curl|sh installer (BusyBox POSIX sh / bash / dash)
├── install.py        # stdlib Python installer wizard (fallback for pure-Python platforms)
├── pyproject.toml    # PyPI package definition (pip install navig-mini)
├── .env.example      # Full environment variable reference
├── CURRENT_PHASE.md  # Active development phase tracker
├── DEV_PLAN.md       # Full development plan
└── navig_mini/
    ├── __init__.py   # Package init — version 1.1.0
    └── cli.py        # navig-mini CLI: init/start/stop/restart/status/logs/version

NAVIG Big controller plugin (for navig mini * commands): navig-core/navig/plugins/navig_mini/plugin.py

3 Installation Methods

Method 1 — curl | sh (preferred on NAS / Pi / embedded)

wget -qO- https://navig.run/mini | sh
# or
curl -fsSL https://navig.run/mini | sh

# Unattended (CI / provisioning)
MINI_NO_WIZARD=1 MINI_TOKEN=<bot_token> MINI_CHAT=<chat_id> sh install.sh

# Custom directory / airgapped
MINI_SKIP_CRON=1 MINI_DIR=/opt/navig-mini INSTALL_BASE_URL=http://local.server sh install.sh

Installs to ~/navig-mini/. Persistence: systemd → cron @reboot → manual fallback.

Method 2 — pip install (any machine with Python 3.6+)

pip install navig-mini                           # from PyPI
pip install -e E:/projects/apps/navig/navig-mini    # dev install (this repo)

navig-mini init       # interactive wizard — creates .env in ~/navig-mini/
                      # (from a wheel this fetches the wizard from the plugins mirror;
                      #  set INSTALL_BASE_URL to use your own)
navig-mini start
navig-mini stop | restart | status | logs | version

Method 3 — navig mini * (from NAVIG Big, controls remote device via HTTP/SSH)

navig config set mini.url    http://nas.local:9191
navig config set mini.secret <hmac_secret>
navig config set mini.ssh_host my-nas

navig mini status             # show remote agent health + stats table
navig mini run "df -h"        # HMAC-signed command execution
navig mini deploy             # SSH-upload agent.py + monitor.py → restart
navig mini logs [-n 100]      # tail agent.log via SSH
navig mini restart [service]  # restart agent/monitor/named process
navig mini list --check       # list all agents with live HTTP ping

Agent HTTP API

/stats example response

{
  "version":      "1.1.0",
  "hostname":     "nas-wd",
  "uptime_sec":   3600,
  "ram_free_mb":  512,
  "ram_total_mb": 1024,
  "disk_pct":     "42%",
  "disk_free":    "21G",
  "disk_path":    "/",
  "load":         [0.1, 0.2, 0.1],
  "python":       "3.9.2"
}

/run POST body

{"cmd": "df -h", "timeout": 30}

Header: X-Agent-Sig: <hmac-sha256-hex-digest-of-body>

Commands must match the allowlist. Extra prefixes: AGENT_SAFE_PREFIXES_EXTRA.

Environment Variables

See .env.example for the complete annotated reference.

Security

• All /run requests require X-Agent-Sig: HMAC-SHA256(secret, body)
• Strict command allowlist — cannot execute arbitrary shell
• Binds to 0.0.0.0 — firewall port 9191 on public-facing hosts

Multi-Agent Setup

navig config set mini.agents '[
  {"name":"nas",  "url":"http://nas.local:9191", "ssh_host":"my-nas"},
  {"name":"pi4",  "url":"http://pi4.local:9191", "ssh_host":"pi4"}
]'
navig mini list --check

Target Devices

• WD My Cloud (armv7l, 509MB RAM, BusyBox ash)
• Raspberry Pi 3/4/5
• Cheap VPS (512MB RAM)
• Any embedded Linux with Python 3.6+