ARIA-AGENT/satellite/README.md

ARIA Satellit 🛰️

Ein eigenständiger Außenposten-Container für ein fremdes Netz (Büro, Werkstatt, Ferienwohnung …). Er verbindet sich als RVS-Client in Stefans Raum und gibt ARIA Augen und Hände in genau diesem Netz — ohne dass der Haupt-Stack dort stehen muss.

• Augen (Info): entdeckt Geräte via mDNS/Zeroconf (Chromecast, AirPlay, Sonos, Drucker, NAS …), SSDP/UPnP + DIAL (Smart-TVs, Fire TV) und der ARP-Tabelle (rohe Hosts). Meldet ARIA ein Live-Inventar.
• Hände (Steuerung): DIAL-App-Launch (z.B. YouTube-Video auf dem Fire TV), Wake-on-LAN, generisches HTTP. Nur wenn freigeschaltet (siehe Sicherheit).

⚠️ Wichtig: der Satellit MUSS im echten Ziel-LAN laufen

Discovery (mDNS/SSDP-Multicast + ARP) funktioniert nur, wenn der Prozess tatsächlich im selben LAN wie die Geräte hängt — z.B. 192.168.177.0/24, wo der Fire TV steht.

Docker Desktop (Mac/Windows) geht NICHT. Dort ist network_mode: host das Netz der Docker-Linux-VM (NAT, 192.168.65.x / 172.x), nicht dein echtes LAN. Der Satellit sieht dann nur Docker-Container statt der echten Geräte. (Der Satellit erkennt das selbst und meldet eine ⚠-Warnung im Diagnostic + Log.)

Richtig deployen — zwei Wege:

A) Linux-Box im Ziel-LAN mit Docker Engine (empfohlen, z.B. Raspberry Pi / NUC im Büro):

cd satellite
cp .env.example .env            # RVS-Zugang + SATELLITE_LOCATION
docker compose up -d --build
docker compose logs -f          # "Netz: primary_ip=192.168.177.x" + "[scan] N Geraete"

network_mode: host (schon gesetzt) gibt hier echtes LAN + Multicast.

B) Nativ als Python-Prozess (für Mac/Windows-Test oder ohne Docker) — läuft direkt auf einer Maschine im Ziel-LAN. Das Script lädt die .env selbst (muss im satellite/-Ordner liegen):

cd satellite
cp .env.example .env      # RVS-Zugang + SATELLITE_LOCATION eintragen
pip install -r requirements.txt
python satellite.py       # liest .env automatisch

(Echte Umgebungsvariablen haben Vorrang — export RVS_TOKEN=... überschreibt die .env, falls du das lieber magst.)

RVS_HOST/PORT/TLS/TOKEN identisch zum Haupt-Stack (gleicher Raum, damit ARIA den Satelliten erreicht). SATELLITE_LOCATION ist der Name, über den ARIA das Netz anspricht („Büro").

Kontrolle: im Log/Diagnostic muss primary_ip im Ziel-LAN liegen (192.168.177.x) — steht da 192.168.65.x oder 172.x, sitzt der Satellit im falschen (Docker-)Netz.

Als Dienst installieren (Autostart, ohne Docker)

Legt automatisch ein .venv an, installiert die Requirements und richtet einen Dienst ein, der bei Boot startet und bei Absturz neu hochkommt. .env vorher anlegen.

Linux (systemd) / macOS (launchd):

cd satellite
bash install.sh              # installieren + starten
bash install.sh uninstall    # entfernen

• Linux-Logs: journalctl -u aria-satellite -f
• macOS-Logs: tail -f satellite.log (evtl. „Lokales Netzwerk"-Zugriff erlauben)

Windows (Scheduled Task) — PowerShell als Administrator:

cd satellite
powershell -ExecutionPolicy Bypass -File install.ps1              # installieren + starten
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall  # entfernen

• Log: Get-Content -Wait satellite.log

So nutzt ARIA es

ARIA hat drei Brain-Tools:

• satellite_list — welche Netze/Satelliten sind online + was können sie.
• satellite_devices(satellite) — Inventar eines Netzes.
• satellite_command(satellite, device, action, params) — Aktion ausführen.

Beispiel „YouTube-Video auf dem Büro-Stick":

satellite_command(satellite="Büro", device="Fire TV",
                  action="dial.launch", params={"app":"YouTube","v":"<videoId>"})

Sicherheit

Der Satellit scannt ein Netz und ist über einen Cloud-Relay erreichbar — deshalb:

• Reagiert nur auf den eigenen RVS-Raum (Token).
• CONTROL_ENABLED=false = reiner Info-Satellit (steuert nichts). Standard-sicher.
• Bei true: nur Aktionen aus CONTROL_ALLOWLIST, alles andere wird abgelehnt.
• Jede ausgeführte Aktion wird geloggt.
• Keine offenen Ports — reiner Client.

Empfehlung: in vertrauenswürdigen Netzen CONTROL_ENABLED=true mit enger Allowlist; sonst false und nur beobachten.