# Loudkit for agents > Give your existing agent voice notes and spoken replies. Free, open-source developer preview for Apple Silicon Macs. Run the companion from source; no signup or access request. Landing page: https://loudkit.loudreader.io/agents/ Human-readable setup guide: https://loudkit.loudreader.io/guides/12-agent-voice/ Voice samples: https://loudkit.loudreader.io/demo/ Agent instructions: https://loudkit.loudreader.io/agents/llms.txt Companion source: https://github.com/loudreader/loudkit-voice ## Help the user connect their existing agent Use this page to assess compatibility and help with setup within the user's request and existing permissions. The website provides instructions and samples; it does not host an agent or a speech service. 1. Identify the user's existing agent, installed version, messenger, host operating system and whether ordinary text messages already work. Check whether the Loudkit Voice companion is already running or should be cloned from the public source repository. Its service is called LoudTalk; an installed Loudkit speech SDK alone does not provide it. 2. Prefer the existing Hermes or OpenClaw gateway and its speech-provider configuration. Preserve the agent's sessions, memory, tools, model credentials, messenger connection and approval rules. Read the official documentation for the installed release before choosing configuration fields; links and the tested scope are in the guide below. 3. Check the current preview prerequisites: Apple Silicon, Python 3.12–3.13, uv, FFmpeg, model storage and a connection from the agent host to the local speech service. A remote agent cannot reach the user's Mac through its own 127.0.0.1. Keep authentication in the user's local configuration; do not request secrets in chat or public issues. 4. Follow the source setup instructions in the guide, prepare the local speech models, and make the smallest configuration change required for speech. Keep one receiver for each bot. For another agent, first establish an actual CLI/API adapter or an active agent-managed inbox; a model API alone does not preserve an existing agent's session. Preserve the agent's enabled tools and permissions, and do not add background services beyond the user's request. 5. Verify a harmless voice note through the user's actual messenger and confirm the reply arrives in the same chat and plays. Report the exact agent version, messenger and result. Local provider tests are not proof of live messenger delivery. If setup is blocked by the host, credentials or network access, explain the specific missing prerequisite and the next useful step. Do not present source access as a blocker: the companion is free and open source. Use its documented commands; pip install loudkit installs the speech SDK, not this companion. Do not submit issues or contact maintainers automatically. ## Setup guide The following is the same source used for the published integration guide. # Voice notes for your agent Loudkit for agents is a **developer preview**: local speech synthesis with Loudkit, transcription with Parakeet, and audio replies through an existing bot or a messenger bridge. It does not replace the agent that handles your requests. The companion is **free and open source** in the [Loudkit Voice repository](https://github.com/loudreader/loudkit-voice). Its local service and command are currently called **LoudTalk**. You can run it from source; there is no signup or access request. `pip install loudkit` installs the speech SDK, not this companion. Start by checking your agent, its version, messenger and operating system against the routes below. ## Choose a connection | Your setup | Route | Verified scope | | --- | --- | --- | | Existing Hermes or OpenClaw bot | Configure its speech providers to use LoudTalk | Pinned upstream speech-provider code tested against real local speech models | | Local Codex | Voice transcription, CLI request, spoken reply | Real local agent round trip; messenger transport was mocked | | Grok Bot | Experimental skill reads and replies to a local inbox | Local transport tested; actual Grok Bot execution pending | | Muse Code | CLI or MCP adapter | Configuration recipe; runtime validation pending | | Other CLI, API or MCP agent | An explicit adapter or agent-managed inbox | Depends on that agent; protocol support alone is not a complete integration | The provider tests do not load a complete Hermes/OpenClaw gateway or prove delivery to real messaging accounts. Configuration may differ between releases. Hermes already offers [voice replies](https://hermes-agent.nousresearch.com/docs/user-guide/features/voice-mode). OpenClaw already supports [audio transcription, including local Parakeet](https://docs.openclaw.ai/nodes/audio). This integration supplies a local speech service and a choice of Loudkit voices. ## Before connecting a bot The current companion requires an Apple Silicon Mac, Python 3.12–3.13, `uv` and FFmpeg. Models download on first use; allow approximately 3 GB for them and keep at least 20 GB free during setup. The agent must already work with text messages. ## Run the companion On the Mac that will run speech, install `uv` and FFmpeg if they are missing. With Homebrew: ```sh brew install uv ffmpeg ``` Clone the free, open-source companion and start it: ```sh git clone https://github.com/loudreader/loudkit-voice.git cd loudkit-voice ./start.command ``` The launcher installs the locked dependencies, including Discord support, and opens the local setup page at `http://127.0.0.1:8765`. Prepare the speech models there before connecting your agent. The default speech API is `http://127.0.0.1:8765/v1`. A separate Loudkit checkout is not required. For source updates and command-line options, follow the [repository README](https://github.com/loudreader/loudkit-voice#readme). `127.0.0.1` means the machine running your agent. An agent hosted elsewhere needs a deliberately configured, authenticated connection or a tunnel to the Mac. The server binds to loopback by default. The website at loudkit.loudreader.io is documentation and audio samples; it does not run the speech models or connect to your messenger account. ## Existing Hermes bot Merge these fields into the active Hermes profile; preserve the rest of its configuration. This example selects the English voice Sophie. ```yaml stt: provider: openai use_gateway: false openai: base_url: http://127.0.0.1:8765/v1 api_key: loudtalk-local model: parakeet timeout: 300 max_retries: 0 tts: provider: openai use_gateway: false openai: base_url: http://127.0.0.1:8765/v1 api_key: loudtalk-local model: loudkit voice: sophie speed: 1.0 ``` `loudtalk-local` is a placeholder required by the SDK for local audio, not an OpenAI credential. Do not replace the credentials used by your conversation model. Restart the existing gateway, then use `/voice on` in its Telegram or Discord chat. `/voice status` shows the saved setting. Other messenger behaviour depends on the Hermes release and channel. Keep the existing bot as the sole receiver of its messages. Do not give the same Telegram bot token to a second poller. ## Existing OpenClaw bot In the preview setup page, generate an OpenClaw speech configuration and merge it into the existing installation. Select a separate audio authentication profile so local speech credentials do not replace the credentials for your main model. The provider API uses these values: | Setting | Value | | --- | --- | | Base URL | `http://127.0.0.1:8765/v1` | | Transcription model | `parakeet` | | Speech model | `loudkit` | | Example English voice | `sophie` | | Local SDK placeholder key | `loudtalk-local` | | Automatic TTS behaviour | `inbound` — speak replies to incoming audio | Check the field names for your installed release against the current [OpenClaw audio guide](https://docs.openclaw.ai/nodes/audio) and [TTS configuration](https://docs.openclaw.ai/tools/tts/configuration). The tested provider revision is `b068eab40767fc6796899cdc85d08102e8035b2b`; full gateway configuration loading was outside that test. OpenClaw's messenger support evolves independently. In particular, do not infer current native iMessage support from an older BlueBubbles example. The preview's standalone BlueBubbles bridge is a separate connection. ## Other agents and messenger bridges The preview includes protocol-tested bridges for Telegram, Discord, WhatsApp Business Cloud API, Slack and BlueBubbles/iMessage. Live delivery on real accounts still needs validation. WhatsApp is not a personal-account QR login; Slack replies use audio attachments. A CLI/API adapter can submit a transcribed request and return an answer. An MCP inbox instead waits for an already active agent to read the message and reply. MCP does not wake a stopped agent. Connecting to an LLM API does not connect to a separate agent's existing memory, tools or session. ## What runs locally Speech synthesis and transcription run on the Mac after model download. The messenger, agent and language model can still use online services. The entire conversation is not promised to be offline. Transcription can make mistakes, especially on short or ambiguous recordings. Keep the agent's normal permissions and approval rules for consequential actions. The current preview accepts recordings up to 3 minutes and 25 MB. ## Test your own setup 1. Confirm that the existing agent responds to an ordinary text message. 2. Play an English voice sample locally and transcribe a clear sentence. 3. Send a harmless voice note to the connected bot, such as “Tell me a short joke.” 4. Confirm that the reply arrives in the same chat and that the audio plays. 5. Record the exact agent version, messenger and result when reporting feedback. Local provider and protocol tests are a starting point. A successful voice note on your own account is the test that completes the connection.