> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/mobile/voice-on-mobile.md). # Voice on Mobile Talk to your desktop coding agents from your phone. The mobile voice agent listens, relays what you say to a session running on your desktop, and speaks the result back to you. Voice Mode is in **alpha** while we polish it. Voice is part of the mobile workflow described on the [mobile agent management page](https://nimbalyst.com/mobile-agent-management/). Voice runs in the **iOS** app. ### Before you start Three things need to be in place. 1. **Your phone is paired and signed in.** See [Mobile App](/mobile/mobile-app.md) for pairing and sync setup. 2. **Your desktop is running and connected.** Voice on mobile drives sessions on your computer, so the desktop app has to be awake and syncing. Sleep prevention under **Settings > Account > Mobile App** on desktop keeps the connection alive while you are away from your desk. 3. **An OpenAI API key has synced to your phone.** Voice Mode runs on OpenAI's realtime voice models, and your phone gets the key from your desktop rather than from a field you type into. To check the key, open **Settings → Voice Mode** in the mobile app. The **OpenAI API Key** row should read **Synced from desktop** with a green check. If it reads **Not synced yet**, set an OpenAI key on the desktop under **Settings > Application > Voice Mode**. A Claude or Codex agent login on its own is not enough. See [AI Provider Setup and Notifications](/setup-nimbalyst/ai-provider-setup-and-notifications.md). Your desktop pushes the key a few seconds after your phone connects, and again on every reconnect, so reopening the mobile app is the quickest way to trigger a resync. ### Start a voice session There is no permanent mic button on the main screens. Voice stays off until you start it from a menu, and the floating mic appears once it connects. **Project-wide**, where the voice agent can work with any session in the project or create a new one: 1. Open a project so you are on its session list, **Sessions** tab. 2. Tap **+** in the top right. 3. Tap **Start Voice Agent**. **Focused on one session**, where everything you say targets that session: 1. Open the session. 2. Tap **•••** in the top right. 3. Tap **Start Voice Mode**. The first time you start voice, iOS asks for microphone permission. Voice cannot connect without it. To end a session, tap **Cancel** on the floating mic, open a session's **•••** menu and choose **Stop Voice Mode**, or just tell the voice agent to stop. ### The floating mic Once connected, a floating mic sits at the bottom of the screen and a small status pill appears in the navigation bar. | Control | What it does | | ---------- | -------------------------------------------------------------------------------------------------- | | **Mic** | Tap to talk, to resume after the mic has gone idle, or to interrupt the agent while it is speaking | | **Pause** | Releases the mic while listening, or stops the agent mid-sentence while it is speaking or thinking | | **Resume** | Brings the mic back after an idle timeout | | **Cancel** | Ends the voice session | The mic ring pulses amber with a small badge while the voice agent runs a tool, so you can watch it look something up instead of wondering whether it heard you. The status pill mirrors the same states: a filled mic while listening, a speaker while speaking, and dots while it is thinking. ### Sending a task to a session Coding requests are not fired off the instant you finish talking. A card slides up showing the target session and the exact prompt, with a countdown running. **Cancel** drops it, **Send Now** skips the wait, and doing nothing sends it when the countdown ends. The pause gives you a chance to catch a misheard request before it reaches the agent. Set the length of the countdown under **Settings → Voice Mode → Confirm Delay**. Once sent, the prompt queues on your desktop like any other mobile prompt and runs on your machine. ### What you can ask for * Start a new session. The device that asked for it opens the session once it exists, and your other devices just see it appear in their list. * Find a session by topic, described in your own words. * Switch between sessions. * Summarize a session, including any question it is waiting on. * Answer a session's pending question by voice. * Send a new coding task to a session. * Ask the coding agent a question and wait for the spoken answer. * Look something up in your project's docs, plans, and decisions, answered from your desktop's project memory when it is available. ### Idle and wake After a stretch with nothing happening (30 seconds by default) the mic goes idle. The connection stays up and the microphone is released, so the app is not listening in the background. Tap the mic or **Resume** to pick up where you left off. With **Auto-Announce Completions** on, a session finishing wakes voice back up and speaks the result. You can kick off work, put the phone in your pocket, and hear how it went. ### Mobile voice settings Under **Settings → Voice Mode** in the mobile app: * **OpenAI API Key.** Status of the key synced from your desktop. Read-only. * **Voice.** The spoken voice. Your desktop's voice preference syncs here, so both devices sound the same unless you pick a different one on the phone. * **Idle Timeout.** How long the mic stays open with nothing happening, from 10 to 120 seconds. * **Auto-Announce Completions.** Whether a finished session wakes voice to speak its result. * **Confirm Delay.** The countdown on the pending prompt card, from 1 to 10 seconds. The spoken language follows the preferred agent language configured on your desktop, whatever language you speak in, and falls back to English when no preference is set. ### Troubleshooting **No Start Voice Agent in the + menu.** The item appears on the **Sessions** tab of a project and only while voice is off. Switch back from the **Files** tab if you are on it. If voice is already running, the session menu offers **Stop Voice Mode** instead. **"Sync an OpenAI API key from Nimbalyst on your Mac."** Your phone has no key yet. Set one on the desktop under **Settings > Application > Voice Mode**, confirm the desktop is running, then reopen the mobile app to trigger a resync. The row under **Settings > Voice Mode** on mobile should change to **Synced from desktop**. **Microphone permission denied.** Grant it under iOS Settings → Nimbalyst → Microphone, then start voice again. **Voice ends when the connection drops.** Mobile does not silently reconnect the way desktop does. If the connection is lost, the voice session ends and you start it again from the menu. **Nothing reaches the desktop.** Check the connection indicator in the project list. Voice relays through the same encrypted sync channel as your sessions, so if sessions are not updating, voice commands will not land either. A sleeping desktop is the usual cause, which is what sleep prevention is for. ### A note on stability Voice Mode is alpha and may change, break, or be removed without notice. If you hit a problem, share feedback via Discord or our support channels. See [Feedback, Discord, Support, Releases](/getting-started/feedback-discord-support-releases.md). For the desktop side and the full settings panel, see [Voice Mode](/setup-nimbalyst/voice-mode.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nimbalyst.com/mobile/voice-on-mobile.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.