---
title: "Vulpine on iPhone"
description: "The GPUI-owned iOS app: Talk with hold-to-talk and the voice state chip, Connect by invitation code behind the GatewayLink trait, Settings; the state model, the audio start order (the settle order by default, --audio-legacy) and the reply's rate after a route change, the launch arguments, and how to build, test and screenshot it in the simulator."
type: "living"
source: "apps/phone/README.md"
verified: "2026-11-14"
group: "Frontends"
---

> **Living doc**, checked against the code 2026-11-14

Vulpine on iPhone, in development: a GPUI app over the in-process Rust core (`crates/phone_core`). It is not yet
released; this page says what the current build does. Its display name is Vulpine and its bundle id is
`com.voidfab.vulpine.phone` (`Info.plist`); device builds sign as `com.voidfab.vulpine.phone.dev`. How to build, test
and change it is in `apps/phone/DEVELOPING.md`.


## The screens

- **Talk** (home when a gateway is paired): the shared conversation panel, the voice state as a chip (warming, idle,
  listening, thinking, speaking) beside the gateway's status, and a large hold-to-talk button at the thumb. Finger down
  routes the mic to the turn, lifting it commits the turn, and sliding off cancels it. Typing in the panel's input row is
  the second path. The audio comes up when Talk opens and stays up while Talk is on screen, so a hold only starts
  capture. Until it is ready the chip reads "warming", and a hold reads "Warming the mic... keep holding". The chip is
  back on idle, and the button takes the next hold, as soon as the reply's last sample has played.
- **Connect** (home when nothing is paired): paste the invitation code from the Gateway window (Reach, Pair a phone). The
  screen shows the paired gateway's name, how it is reached (on this network, or through its relay), its status and
  Forget. QR scanning is not built yet; its button says so. Pairing redeems the code off the UI thread ("Pairing..."
  meanwhile) and saves the record in the app's own folder, and the next launch opens on Talk. Forget removes the record
  and the phone's key. No code, token, key or endpoint id is shown or logged: a failure names the step that failed, in
  plain words. Pairing goes through the `GatewayLink` trait (`src/link.rs`): `PhoneCoreLink` (`src/core_link.rs`) with
  `--features core`, else `StandInLink`, which checks the code's shape and dials nothing.
- **Settings**: speak replies out loud (on by default), reduce motion (from the system at launch), the text size (the
  system's Dynamic Type), Appearance, Sounds, Haptics, Follow-up, **Share diagnostics**, and about (version,
  build commit, link kind, audio start order). Choices are kept between launches, and a saved choice wins over the
  launch defaults. Conversation (at the bottom) says what Talk keeps between launches and holds the "Clear
  conversation" row (unavailable when Talk is empty).

What the phone keeps (`src/store.rs`): one owner-only folder in its container,
`Library/Application Support/com.voidfab.vulpine.phone` (0700), holding `settings.json` (0600) and `reach/`, the pairing
record (the phone's key and the gateway's address, 0600). The key is a file inside the app's container, not in the
Keychain. `--paired` (the screenshots' stand-in) keeps nothing.

`conversation.json` (0600, iOS protection class "until first unlock") keeps the last conversation's text, so Talk shows
it after a relaunch with each user line marked "earlier". It holds the user lines, the replies' words and the cards,
never audio: at most the newest 50 turns and 200 KB. It is written when a turn ends and when the app leaves the
foreground. "Clear conversation" and a successful Forget remove it. It is never logged (counts and bytes only), never
in a diagnostics share, and never sent.

A push-to-talk turn is also written when it ends, since an app killed from the app switcher gets no background
event after it. A self-test launch shows what is kept but never writes it (`HS1-CONVO not-kept why=self-test`), so
generated speech and scripted presses stay out of the history. A self-test launch is any launch argument except
`--appearance`, `--audible`, `--reduce-motion`, `--type-size`, `--screen`, `--workspace`, `--audio-legacy` and the
runner's `--diagnostic-run` marker. `--keep-history` makes such a launch keep the history like a real one, for the
device check of this rule.

**Share diagnostics** copies `phone.log` and `phone.prev.log` off the UI thread and opens the iOS share sheet. The logs
hold counts, milliseconds and closed words only, never transcripts or credentials. Canceling removes the copies and
keeps the original logs, so you can share again. If removing a finished share's copies fails, Settings offers **Retry
cleanup**, and another export waits until cleanup succeeds.

Safe areas from GPUI's window insets; the Fox token set dark or light as the system is; text scaled by Dynamic Type;
every tap target at least 44 pt (`native_kit::touch`); nothing draws at rest (the turn is polled only while it runs).


## Appearance

Settings → Appearance offers **System** (the default, following the device), **Light** and **Dark**. A settings file
with no theme or an unknown one uses System. A choice redraws Settings, Connect and Talk in place, the conversation
panel and the status bar included, and keeps drafts and focus. It also clears the developer `--appearance` pin.


## Siri and Shortcuts

Three App Intents, each an App Shortcut with Siri phrases that name the app (Siri also knows it as Fox): **Ask Fox**
sends a typed line to the gateway and the reply is the dialog. **Fleet Status** and **Agents Waiting** read the
gateway's `fleet_readout`, which the gateway answers itself from its fleet store, read only. They run in the app's own
process without opening it, over the same link a typed line uses, and answer within 9 s (Siri gives up near 10 s).
Each run logs one `SI1-INTENT kind=<ask|fleet|agents> ok=<bool> chars=<n> ms=<n>` (or `error=<word>`) line, never the
words.


## Push-to-talk sounds

Settings → Sounds picks one sound family for every push-to-talk moment: Radio, Sparkle, Fox or Tick (the default),
saved as `sounds` in the settings file. Each row's play button plays that family's go cue through System Sound
Services, so it plays while push to talk holds the audio session, and it follows the silent switch.


Sounds can be Off: the group's first row, saved as `sounds_on` beside the kept family, silences every push-to-talk
cue (`PHONE-PTT cue=<m> played=0 why=off`) and the follow-up window's cue; picking a family turns them back on. The
thinking cue is one soft, low sound per family, repeated every 2.8 s while a released press waits for its reply
(`ptt::cues::THINKING_EVERY`, the generator's `THINKING_EVERY_MS`).

## Haptics

A light tap when the hold-to-talk button takes the press, a firmer one when the release sends the turn, and a soft one
when the reply's first frame has played (none when replies play silently). Settings → Haptics (under Sounds, on by
default, `haptics` in the settings file) turns them off. Log lines: `PHONE-HX haptic moment=<press|commit|reply>
feel=<light|firm|soft> played=1 call_us=<n> during_recording=<1|set|refused>`, or `played=0 why=<off|mock|no-engine>`.


## The follow-up window

After a reply has played out on Talk, in the foreground, the microphone stays open for Settings → Follow-up
(Off, 4 seconds by default, or 8 seconds; `follow_up` in the settings file). A ring round the button, a bar that empties and
the sound family's go sound show it. The window's words go up without the wake, and the gateway's follow-up window and
decision model take them or drop them. A press inside the window is an ordinary hold; leaving Talk or the foreground
closes it.

**With push to talk on**, the follow-up window opens only while Talk is on screen in the foreground, never after a
reply heard on the lock screen or in the background (iOS lets an app begin a transmission only in the foreground).


