# Companion Apps

## Confirm The Desktop Connection First

Before pairing another device, open **Settings → Gateway** on the desktop app and confirm that the current Gateway is connected and healthy.

![Gateway connection path used by the desktop and companion apps](https://neotask-marketing-assets-417007889150.s3.us-east-1.amazonaws.com/docs/product/2026-08-13-r1/gateway-connection-path-1280.webp)

## What Are Companion Apps?

Companion apps are native applications for iOS, Android, and macOS that connect to your Gateway as **nodes**. Nodes expose device capabilities, camera, canvas, screen recording, location, voice, and system execution, to your agents.

Think of it this way: the Gateway is the brain, and companion apps are the hands and eyes on your devices.

## How Nodes Work

1. **Connect**, The companion app connects to your Gateway over WebSocket
2. **Pair**, New devices go through a pairing approval process
3. **Register capabilities**, The app tells the Gateway what it can do (camera, canvas, location, etc.)
4. **Agents invoke**, During conversations, agents can request the node to take a photo, record screen, render a canvas, and more

Nodes are **not gateways**, they don't run their own AI. They're peripheral devices that extend what your agents can do.

## macOS Companion App

The macOS app lives in your menu bar and serves as both a companion node and a gateway manager.

### Capabilities
- **Canvas**, Render interactive web content in a native window
- **Camera**, Take photos and video clips (front/back)
- **Screen Recording**, Full-screen or per-app recording
- **System Execution**, Run shell commands on the Mac (gated by exec approvals)
- **Notifications**, Send native macOS notifications with priority options
- **Location**, GPS when available

### Additional Features
- **Gateway Management**, Start, stop, and monitor the Gateway
- **Permission Ownership**, Manages macOS TCC permissions (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, AppleScript)
- **Deep Links**, `neotask://` URL scheme for launching agents with parameters
- **CLI Install**, Installs the `neotask` command-line tool

## iOS App

The iOS app connects as a node to your Gateway, bringing mobile capabilities to your agents.

### Capabilities
- **Canvas**, SwiftUI-based interactive content rendering
- **Camera**, Photos and video clips (front/back cameras)
- **Audio Recording**, Microphone capture
- **Location**, GPS with accuracy selection
- **Notifications**, Native iOS push notifications

### Features
- **Discovery**, Finds your Gateway via Bonjour (LAN), Tailscale (VPN), or manual entry
- **Pairing**, Secure device pairing with approval from the Gateway
- **Voice Wake**, Wake word activation for hands-free interaction
- **Talk Mode**, Continuous voice conversation
- **Share Extension**, Share content from other apps directly to your agent
- **A2UI**, Agent-driven UI rendering on the device canvas

### Limitations
- Foreground-first design (iOS suspends WebSocket connections in background)
- Strict background command restrictions
- Currently in internal preview

## Android App

The Android app connects as a node with capabilities similar to iOS.

### Capabilities
- **Canvas**, Jetpack Compose-based UI rendering
- **Camera**, Photos and video (front/back, permission-gated)
- **Screen Recording**, System screen capture (Android 10+)
- **Location**, GPS with accuracy modes
- **SMS Sending**, On devices with telephony support
- **Chat & History**, View conversation history on device

### Features
- **Foreground Service**, Persistent notification keeps the connection alive
- **Shared Sessions**, Same session across all connected nodes
- **Modern Android**, Requires Android 12+ (API 31)

## Headless Node Host

Run a node without any UI, ideal for build servers, remote machines, or headless Linux boxes.

### Capabilities
- **System Execution**, Run commands on the node host
- **Command Allowlist**, Configure which commands the node can execute
- **Persistent Service**, Install as launchd/systemd service

### Use Cases
- CI/CD build agents, Let your AI agent trigger builds on a remote server
- Home lab automation, Run commands on a Raspberry Pi or home server
- Multi-machine orchestration, Coordinate tasks across multiple machines

## Device Pairing

### Pairing Flow
1. Companion app presents its device identity (fingerprint + public key)
2. Gateway issues a pairing approval request
3. You approve the device through the desktop app or dashboard
4. Gateway issues a device token for future connections

### Trust Model
- **Local devices** (loopback) are auto-approved for convenience
- **Non-local devices** require explicit approval
- Device tokens are stored locally and reused on reconnect

## Exec Approvals

For nodes that can run system commands (macOS, headless hosts), exec approvals control what's allowed:

- **Allowlist mode**, Only pre-approved commands can execute
- **Ask mode**, Unknown commands prompt you for approval
- **Full mode**, No restrictions (use with caution)

Configure per-node allowlists to precisely control what each device can do.