Guida OASI Device Agent

L'OASI Device Agent è una piccola app che gira sul tuo computer e gli permette di collaborare con OASI: stampare uno scontrino, leggere un codice a barre, sincronizzare una cartella, ricevere assistenza remota e altro. È leggera, silenziosa e sicura: non rallenta il computer, parte da sola e fa solo ciò che l'amministratore ha attivato per te.

Cosa può fare

L'amministratore attiva solo le funzioni che ti servono — magari solo la stampa, magari stampa + scanner. Le possibilità:

Tutto passa per un confine sicuro: l'agente propone, la piattaforma autorizza. Nessuna funzione si attiva da sola e ogni azione sensibile lascia una traccia.

Capire se funziona (senza chiamare nessuno)

L'agente porta con sé una pagina di diagnosi che vive sul computer stesso. Risponde anche quando Internet non va, perché per rispondere non deve chiedere niente a nessuno. Apri il browser su questo indirizzo:

http://localhost:3011/doctor

Ti risponde in una riga alla domanda che conta davvero — questo computer è collegato e abilitato a fare qualcosa? — e, se la risposta è no, ti dice cosa fare. Sono tre controlli:

Il bottone Ricontrolla rifà i controlli sul momento. Se devi aprire una segnalazione, la pagina mostra un codice di supporto: citalo e sappiamo subito di cosa si tratta.

& "$env:ProgramFiles\OASI\PrintAgent\oasi-wrapper-host-agent-rs.exe" doctor

Aggiorna o ripara l'agente

Se l'agente è già installato su questo computer e va aggiornato — o non risponde più — non serve reinstallare da zero. Apri PowerShell come amministratore (tasto destro sul pulsante Start → Windows PowerShell (amministratore)) e incolla questa unica riga, poi premi Invio:

[Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12; irm https://device.oasi.io/releases/wrapper-upgrade.ps1 | iex

Fa tutto da solo in pochi secondi: scarica l'ultima versione, verifica firma e integrità, sostituisce solo il programma — la tua configurazione (stampante, permessi, codici) resta intatta — si riavvia e si ricollega.

$c="$env:TEMP	wipping.crt"; irm https://device.oasi.io/cert/twipping-codesign.crt -OutFile $c
Import-Certificate -FilePath $c -CertStoreLocation Cert:LocalMachineRoot | Out-Null
Import-Certificate -FilePath $c -CertStoreLocation Cert:LocalMachineTrustedPublisher | Out-Null

Installa l'agente

Scegli il tuo sistema operativo: la guida mostra solo i passi che ti servono.

certutil -addstore -f root twipping-codesign.crt
certutil -addstore -f TrustedPublisher twipping-codesign.crt

[Net.ServicePointManager]::SecurityProtocol='Tls12'
$env:OASI_SETUP="<LINK-DI-SETUP>"
$f="$env:TEMP\oasi-install.ps1"; irm https://device.oasi.io/install-win81.ps1 -OutFile $f -UseBasicParsing
powershell -ExecutionPolicy Bypass -File $f

curl -fsSL https://device.oasi.io/install.sh | sh -s -- --setup=<LINK-DI-SETUP>

curl -fsSL https://device.oasi.io/install.sh | sh -s -- --setup=<LINK-DI-SETUP>

Se hai un link di setup (qualsiasi sistema)

Flusso normale: l'amministratore OASI ti invia un link di setup della forma:

https://device.oasi.io/device/setup/dev_xxx/abc123token

Click → pagina con bottone download + tabella copia/incolla device_id + token → wizard riconosce automaticamente i valori. Token validi 90 giorni, rinnovati a ogni collegamento del device.

Flusso alternativo (download diretto sopra): scarica + esegui setup.exe e inserisci a mano nel wizard i valori che l'amministratore ti comunica:

• Gateway URL — già preimpostato a https://device.oasi.io/gateway (gateway unico della piattaforma). Lascialo invariato; cambialo solo per installazioni self-hosted.
• Device ID (es. dev_abc123)
• Bootstrap token (validità 90 giorni, rinnovata a ogni collegamento del device)
• Station (es. cassa-1)
• Stampa POS891 USB — usa la coda stampante di Windows/spooler. Non impostare PRINTER_MODE=usb come default sicuro: il path USB raw richiede driver WinUSB ed è riservato a test mirati. Per stampanti ethernet usa tcp; per debug usa file.

Come capisco se funziona?

Dopo l'installazione:

• Windows: apri Servizi (services.msc) → cerca "OASI Device Agent" → status "In esecuzione".
• macOS: apri Terminale → launchctl list | grep oasi.print-agent → riga visibile.
• Health check rapido: apri health.json (path sotto) → deve avere "connected": true e "last_poll_ts" recente (entro ~30s: a riposo il poll rallenta fino a 30s).

Top problemi

1. Windows SmartScreen blocca l'installer

Click Maggiori info → Esegui comunque. È normale finché non firmiamo con certificato Authenticode (in procurement). Il binario è comunque auditabile: bytes md5 verificabile.

2. La stampa non esce dalla POS891 USB

Controlli, in ordine:

• Cavo USB collegato + alimentazione + carta caricata?
• Su Windows il percorso provato per termiche USB come POS891 è la coda stampante/spooler: la stampante deve stampare dalla pagina di test di Windows prima di coinvolgere OASI.
• Non usare PRINTER_MODE=usb come default: è accesso USB raw, richiede WinUSB e può fallire sui PC dove la POS891 è esposta come normale stampante Windows.
• Se Windows stampa ma OASI no: controlla che il servizio sia in esecuzione e passa all'amministratore i log dell'agente. Il probe winspool/test-print completo arriva nel Commit 2.

3. "connected: false" nel health.json

• L'URL del gateway è raggiungibile? Test: curl https://<gateway-url>/healthz (deve restituire 200 con header X-Client-Version: 1.0.0).
• Token registrazione scaduto (>90 giorni SENZA che il device si sia mai collegato)? Chiedi all'admin un nuovo setup link.
• Firewall blocca outbound HTTPS al gateway? Aggiungi exception in policy IT.

4. Stampa formato sbagliato (carta esce ma testo storto)

Il wrapper v1.0.0 NON ha PRINTER_LINE_WIDTH configurabile — la larghezza/font è controllata dai comandi PrintAction nel payload OASI (size: 1=normale, size: 2=doppio). Se vedi formato sbagliato, segnala all'admin: bug nel template OASI, non nel wrapper.

5. Assistenza a distanza — attivare / disattivare

Se lo consenti, il supporto OASI può consultare alcune informazioni del tuo computer (entro una lista ristretta e sicura) per aiutarti a risolvere un problema. Ogni accesso viene registrato, e di default questa funzione è disattivata — la attivi solo tu, quando serve.

Puoi gestirla in due modi:

• config.json (controllo grezzo, sempre disponibile):

  "inspection": {"enabled": false}

  Salva → il wrapper rileva la modifica entro 10s, nessun restart richiesto. Default OFF.
• Tray menu (granularità ADR-2026-045): click sull'icona menubar → sezione "Ispezione AI" → submenu con 5 modalità:
  • Auto-accetta — l'operatore può ispezionare senza prompt (per workstation IT amministrate)
  • Chiedi sempre — popup di conferma a ogni richiesta
  • Password (unattended) — server senza schermo, accesso via password una-tantum
  • Per ruolo operatore — solo operatori con ruolo admin/oasi_support possono ispezionare
  • Disabilitato — ispezione bloccata fail-closed (default per device tipo kiosk)

La kill-switch nel tray (ultima voce) revoca istantaneamente tutte le sessioni di consenso attive — utile per chiudere ogni accesso in emergenza.

5-bis. Supporto remoto — un tecnico ti aiuta vedendo lo schermo

Se hai bisogno di assistenza dal vivo, un tecnico OASI può vedere il tuo schermo (solo dopo tua autorizzazione). Come funziona:

1. L'operatore OASI apre da workspace https://<tuo-progetto>.oasi.io/studio/devices/<dev_id>/teleassist e clicca "Avvia assistenza remota".
2. Il workspace ti mostra un comando paste-and-run del tipo:

   oasi-wrapper-remote-assist-rs remote-session \
     --session-id <uuid> \
     --invite-token <hex64> \
     --signaling-url wss://teleassist.oasi.io/ws/ws/teleassist

3. Copia/incolla quel comando nel terminale del computer da assistere ed eseguilo: si collega in modo sicuro al supporto OASI e condivide lo schermo. La prima volta su Mac il sistema chiede il permesso di registrazione schermo — autorizzalo in Impostazioni di sistema → Privacy e sicurezza → Registrazione schermo.
4. Il tecnico vede il tuo schermo nel browser per assisterti: non può muovere il mouse né sentire audio, potete solo scrivervi in chat. La sessione è singola e scade dopo 30 minuti.

Per i sysadmin: la sessione è bind-ata al device_id registrato; l'operatore non può iniziare teleassist su un PC non-suo. Audit lato server registra ogni mint + ogni dial.

6. Aggiornamento

Mac / Linux: auto-update OTA. La piattaforma invia il comando agent.update; il wrapper scarica il nuovo bundle, ne verifica lo SHA-256, fa uno swap atomico dei binari (rollback automatico da .bak se fallisce) e si riavvia. Nessuna azione manuale.

Windows (wizard): OTA non ancora attivo. Per aggiornare scarica il nuovo wizard dal portal e re-installa sopra — la config (gateway URL, device_id, station) viene preservata.

Windows 8.1 (agent PowerShell): ri-esegui il comando di installazione (vedi sopra) — riscarica l'ultima versione dell'agent e preserva la config.

In tutti i casi il gateway impone una versione minima del client (MIN_CLIENT_VERSION): un agent troppo vecchio riceve 403 version_incompatible a /devices/connect finché non viene aggiornato. La versione di ogni device è visibile lato studio (header X-Client-Version + manifest).

Dove sono i log?

Audit del supporto remoto Claude (append-only JSONL, mai cancellato):

Disinstallazione

Windows: Pannello di Controllo → Programmi → OASI Device Agent → Disinstalla. Rimuove servizio NSSM + binari. I file in %ProgramData%\OASI\ restano per ispezione post-mortem (audit log compliance).

macOS: manuale, 3 comandi:

launchctl unload ~/Library/LaunchAgents/io.oasi.print-agent.plist
launchctl unload ~/Library/LaunchAgents/com.oasi.wrapper-tray.plist 2>/dev/null
rm ~/Library/LaunchAgents/io.oasi.print-agent.plist ~/Library/LaunchAgents/com.oasi.wrapper-tray.plist

Per cancellare anche binari + config + cache:

rm -rf ~/Library/Application\ Support/OASI ~/.oasi

I log in ~/Library/Logs/OASI/PrintAgent/ sono lasciati intenzionalmente per ispezione post-mortem (audit log compliance) — cancella manualmente se vuoi pulire completamente.