Settings reference
Understand each iOS setting and how it relates to the computer configuration.
Settings are split between your account and each installed computer. Account settings follow you across devices. Installed integrations cache the account values they need in ~/.agentapprove/env. The installer creates that file, and later requests can update selected values through configuration sync.
iOS settings
| Setting | What it controls | Default | Scope |
|---|---|---|---|
| Mobile Q&A | Sends supported Claude Code questions to the iPhone instead of leaving them in the terminal. | Off, which uses the terminal | Account; cached by supported installed hooks |
| Agent Completion | Sends a notification when a supported agent reports that it stopped. | On | Account |
| Voice Follow-up | Opens a voice or text prompt when a supported live session stops. | Off | Account |
| Privacy Level | Chooses how much command content remains in event history. | Full Content | Account; cached by installed integrations |
| Data Retention | Chooses how long events remain available in your history. | 30 Days | Account |
| End-to-End Encryption | Encrypts supported event content for your devices. Approval Mode also sends a separately encrypted copy to the service for policy evaluation. | On | Account and paired computers |
| Rotation Period | Chooses how often a new event-encryption key is derived. | Off | Account and paired computers |
| Key Retention | Chooses how many older keys remain available for opening older encrypted events. | Keep All | Account policy applied to keys in the device Keychain |
Policy selection and Allow List or Deny List changes are account settings, but they live under Policy rather than Settings.
Status rows
The bottom of Settings shows whether the iPhone has a live server connection and whether the paired Apple Watch is currently reachable. Use the cloud button for connection controls and plan details. See Connection status and account access and Apple Watch for the related controls.
Data controls
The Data section contains actions for restoring the built-in policies, clearing stored history, and closing the account. Each action opens a confirmation that describes its scope. Policy restoration replaces custom policy changes. Clearing history removes event history and conversations and resets agent status. Account closure is different from signing out or cancelling renewal.
See Policies and default behavior before restoring policies. See Trial, subscription, and account closure before closing an account.
Computer configuration file
Run npx agentapprove install to change computer settings. Hand editing can leave the local and account copies out of sync.
| Configuration entry | Installer choice | Related iOS setting |
|---|---|---|
AGENTAPPROVE_API | Service address | None. Keep the installed value unless support gives you a different public endpoint. |
AGENTAPPROVE_TOKEN | Pairing result | None. Use refresh or pair instead of editing it. |
AGENTAPPROVE_PRIVACY | Privacy tier | Privacy Level |
AGENTAPPROVE_RETENTION_DAYS | 1, 7, 30, 90, or 365 days | Data Retention |
AGENTAPPROVE_DEBUG_LOG | Debug logging | No iOS toggle. Run the installer to change it. |
AGENTAPPROVE_E2E_MODE | Approval Mode or Observe Mode | The security mode chosen during install |
AGENTAPPROVE_E2E_ENABLED | End-to-end encryption | End-to-End Encryption |
AGENTAPPROVE_FAIL_BEHAVIOR | Allow, Deny, or Ask when the service cannot be reached | Offline fallback chosen during install |
AGENTAPPROVE_CONFIG_SET_AT | Sync timestamp | None. The installer manages it. |
Voice Follow-up, completion notices, the active policy, and policy lists remain service-side account settings. Supported hooks cache the local values needed for Mobile Q&A and other request behavior.
The service currently waits up to five minutes for a manual approval and up to five minutes for a Voice Follow-up reply. Those values are not exposed as iOS controls. A manual approval timeout denies the request. A Voice Follow-up timeout sends no follow-up message and releases the waiting hook.
When settings reach a computer
Account configuration is returned with normal agent traffic. After you change a supported setting in the iOS app, the next event or approval response from each computer carries the newer configuration back to its local cache. Until a computer sends an event, its file can still show the old value.
Changes include timestamps. If you rerun the installer after changing the iOS setting, the most recent valid change wins.
Check what a computer is using
Run npx agentapprove status. It reports the configuration and installed hooks without printing the full token. If the app and computer disagree, run a normal request so the integration can receive current account settings. Rerun npx agentapprove install if the integration is missing, its local configuration is damaged, or the mismatch remains.
Never paste the contents of ~/.agentapprove/env, pairing files, or encryption-key files into a support message.