# Companion-apps

## Wat zijn companion-apps?

Companion-apps zijn native applicaties voor iOS, Android en macOS die verbinding maken met uw Gateway als **nodes**. Nodes stellen apparaatmogelijkheden beschikbaar, camera, canvas, schermopname, locatie, spraak en systeemuitvoering, aan uw agents.

Zie het zo: de Gateway is het brein, en companion-apps zijn de handen en ogen op uw apparaten.

## Hoe nodes werken

1. **Verbinden**, De companion-app maakt verbinding met uw Gateway via WebSocket
2. **Koppelen**, Nieuwe apparaten doorlopen een koppelingsgoedkeuringsproces
3. **Mogelijkheden registreren**, De app vertelt de Gateway wat hij kan doen (camera, canvas, locatie, enz.)
4. **Agents roepen aan**, Tijdens gesprekken kunnen agents de node verzoeken een foto te maken, het scherm op te nemen, een canvas te renderen en meer

Nodes zijn **geen gateways**, ze voeren geen eigen AI uit. Het zijn randapparaten die uitbreiden wat uw agents kunnen doen.

## macOS Companion-app

De macOS-app bevindt zich in uw menubalk en fungeert zowel als companion-node als als gateway-beheerder.

### Mogelijkheden
- **Canvas**, Interactieve webinhoud renderen in een native venster
- **Camera**, Foto's en videoclips maken (voor/achter)
- **Schermopname**, Volledig scherm of per-app opname
- **Systeemuitvoering**, Shellopdrachten uitvoeren op de Mac (beveiligd door uitvoeringsgoedkeuringen)
- **Meldingen**, Native macOS-meldingen verzenden met prioriteitsopties
- **Locatie**, GPS indien beschikbaar

### Aanvullende functies
- **Gateway-beheer**, De Gateway starten, stoppen en bewaken
- **Rechtenbeveiliging**, Beheert macOS TCC-rechten (Meldingen, Toegankelijkheid, Schermopname, Microfoon, Spraakherkenning, AppleScript)
- **Deep links**, `neotask://` URL-schema voor het starten van agents met parameters
- **CLI-installatie**, Installeert het `neotask` opdrachtregelgereedschap

## iOS-app

De iOS-app verbindt als node met uw Gateway en brengt mobiele mogelijkheden naar uw agents.

### Mogelijkheden
- **Canvas**, Op SwiftUI gebaseerde interactieve contentrendering
- **Camera**, Foto's en videoclips (voor/achtercamera's)
- **Audio-opname**, Microfooninput vastleggen
- **Locatie**, GPS met nauwkeurigheidsselectie
- **Meldingen**, Native iOS-pushmeldingen

### Functies
- **Detectie**, Vindt uw Gateway via Bonjour (LAN), Tailscale (VPN) of handmatige invoer
- **Koppeling**, Veilige apparaatkoppeling met goedkeuring van de Gateway
- **Spraakactivering**, Wake word-activering voor handsfree interactie
- **Gespreksmodus**, Continu spraakgesprek
- **Deelextensie**, Deel inhoud van andere apps rechtstreeks met uw agent
- **A2UI**, Door agent aangestuurde UI-rendering op het apparaatcanvas

### Beperkingen
- Voorgrond-eerst ontwerp (iOS onderbreekt WebSocket-verbindingen op de achtergrond)
- Strikte beperkingen voor achtergrondopdrachten
- Momenteel in intern preview

## Android-app

De Android-app verbindt als node met mogelijkheden vergelijkbaar met iOS.

### Mogelijkheden
- **Canvas**, Op Jetpack Compose gebaseerde UI-rendering
- **Camera**, Foto's en video (voor/achter, rechtenbeveiligd)
- **Schermopname**, Systeemschermopname (Android 10+)
- **Locatie**, GPS met nauwkeurigheidsopties
- **SMS-verzending**, Op apparaten met telefonieondersteuning
- **Chat en geschiedenis**, Gespreksgeschiedenis bekijken op het apparaat

### Functies
- **Voorgronddienst**, Aanhoudende melding houdt de verbinding actief
- **Gedeelde sessies**, Dezelfde sessie over alle verbonden nodes
- **Modern Android**, Vereist Android 12+ (API 31)

## Headless node-host

Voer een node uit zonder gebruikersinterface, ideaal voor build-servers, externe machines of headless Linux-boxen.

### Mogelijkheden
- **Systeemuitvoering**, Opdrachten uitvoeren op de node-host
- **Opdracht-toegestane lijst**, Configureer welke opdrachten de node kan uitvoeren
- **Aanhoudende service**, Installeren als launchd/systemd-service

### Gebruiksscenario's
- CI/CD-build-agents, Laat uw AI-agent builds activeren op een externe server
- Thuislabautomatisering, Voer opdrachten uit op een Raspberry Pi of thuisserver
- Orkestratie over meerdere machines, Coördineer taken over meerdere machines

## Apparaatkoppeling

### Koppelingsproces
1. Companion-app presenteert zijn apparaatidentiteit (vingerafdruk + publieke sleutel)
2. Gateway stuurt een koppelingsgoedkeuringsverzoek
3. U keurt het apparaat goed via de desktopapp of het dashboard
4. Gateway geeft een apparaattoken uit voor toekomstige verbindingen

### Vertrouwensmodel
- **Lokale apparaten** (loopback) worden automatisch goedgekeurd voor het gemak
- **Niet-lokale apparaten** vereisen expliciete goedkeuring
- Apparaattokens worden lokaal opgeslagen en hergebruikt bij opnieuw verbinden

## Uitvoeringsgoedkeuringen

Voor nodes die systeemopdrachten kunnen uitvoeren (macOS, headless hosts) bepalen uitvoeringsgoedkeuringen wat is toegestaan:

- **Toegestane-lijstmodus**, Alleen vooraf goedgekeurde opdrachten kunnen worden uitgevoerd
- **Vraagmodus**, Onbekende opdrachten vragen om goedkeuring
- **Volledige modus**, Geen beperkingen (gebruik met voorzichtigheid)

Configureer per-node toegestane lijsten om nauwkeurig te beheren wat elk apparaat kan doen.