> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yespapa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile App

> Push notifications and one-tap approvals with the YesPaPa mobile app

The YesPaPa mobile app adds push notifications and one-tap approvals on top of the TOTP gate. It's optional and always free.

<Card title="Download the App" icon="mobile" href="https://get.yespapa.app">
  Get YesPaPa for iOS and Android at **get.yespapa.app**
</Card>

## Pairing

### QR Scan (Recommended)

During `yespapa init`, choose to pair with the mobile app. Two QR codes are displayed:

1. **TOTP QR** — Standard `otpauth://` QR scannable by any authenticator app (Google Authenticator, Authy, 1Password). This sets up the TOTP seed for the Inner Ring.
2. **Pairing QR** — A deep-link URL (`yespapa://pair?data=...`) that opens the YesPaPa app and pairs automatically. Contains the remote server config, host ID, pairing token, and TOTP seed.

**Option A: Scan the pairing QR with your phone camera.** If the YesPaPa app is installed, it opens and pairs automatically (TOTP seed + remote config in one step). If not installed, a web page shows install instructions.

**Option B: Scan both QRs from the app.** Tap **Add Host** in the app, scan the TOTP QR first, then scan the pairing QR.

The host appears in your host list immediately. You can pair multiple machines to a single phone.

### Deep-Link Pairing

If you receive a pairing URL (e.g., `https://yespapa.app/pair?data=...`), opening it on your phone will:

* Launch the YesPaPa app if installed
* Show install instructions if not installed
* Preserve pairing data for manual paste after installing

### Manual Pairing

If QR scanning isn't available, you can manually enter the pairing JSON shown during init:

```json theme={null}
{
  "type": "yespapa",
  "totp_seed": "BASE32SEED",
  "host_name": "my-host",
  "remote_url": "https://your-project.supabase.co",
  "remote_key": "your-anon-key",
  "host_id": "uuid",
  "pairing_token": "hex-token"
}
```

## Command Queue

The Command Queue screen shows intercepted commands waiting for approval.

### Viewing Commands

Each pending command shows:

* **Command** — what the agent or user is trying to run (e.g., `rm -rf ./dist`)
* **Justification** — why the command is needed (if the agent provided one)
* **Host** — which machine the command is from
* **Time** — when the command was intercepted

### Approve

Tap **Approve** to allow the command. The app automatically:

1. Generates a TOTP code from the stored seed
2. Sends the code to the remote server
3. The daemon validates the code locally and executes the command

No manual code entry needed — the app handles TOTP generation internally.

### Deny

Tap **Deny** to block the command. The command is rejected and the agent sees a denial in the terminal.

### Approve with Message

Tap **Approve with Message** to approve the command and send feedback to the agent. For example:

* "ok but only delete dist, not src"
* "approved — next time use a safer pattern"
* "fine, but check the backup first"

The message appears in the terminal and is available via the `message` field in JSON events.

## Push Notifications

When a command is intercepted, you receive a push notification on your phone:

```
🔒 YesPaPa — Approval Required
rm -rf ./dist (myhost)
```

Tapping the notification opens the Command Queue directly.

### Requirements

* Physical device (push notifications don't work on simulators)
* Notification permissions enabled for the YesPaPa app
* Valid push token uploaded to the remote server (happens automatically during pairing)

### Troubleshooting

If notifications aren't arriving:

1. Check notification permissions in your device settings
2. Verify `yespapa status` shows "Remote: configured"
3. Check the `hosts.push_token` column in your remote database
4. Review Edge Function logs: `npx supabase functions logs push_notification`

## Grace Periods (Auto-Bypass)

Activate auto-bypass from the **Grace Control** screen to temporarily skip TOTP prompts.

### Activate

1. Select a **scope**: `all`, `destructive`, `git-rewrite`, `privilege`, `network`, or `process`
2. Select a **duration**: 1 hour, 24 hours, or 7 days
3. The app generates an HMAC-signed grace token and syncs it to the remote server
4. The daemon picks it up and auto-approves matching commands

### View Active Bypasses

Active grace periods show:

* Scope (which command bundles are bypassed)
* Remaining time
* When it was created

### Revoke

Tap **Revoke** to immediately expire a grace period. The daemon stops auto-approving commands for that scope.

## Multi-Host Support

Pair multiple machines to a single phone. Each host has:

* Its own TOTP seed
* Its own command queue
* Its own grace periods

Switch between hosts in the app to view and manage commands per machine.

## Security

* **TOTP seed** is stored in the device's secure enclave (iOS Keychain / Android Keystore) via `expo-secure-store`
* **Pairing tokens** are one-time use — once consumed, they cannot be reused
* **TOTP codes** in approvals are validated by the daemon locally — the remote server cannot forge approvals
* **Grace tokens** are HMAC-signed with the TOTP seed — cannot be created without the seed
* If you lose your phone, commands still work via terminal TOTP entry with any authenticator app