From 95cee443013c2850eca30494e93c47aeeb280d02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Stellar=E9=B1=BC?= <2182712990@qq.com>
Date: Mon, 25 May 2026 22:45:12 +0800
Subject: [PATCH] docs: add Docker audio bridge notes

---
 website/docs/user-guide/docker.md             | 78 +++++++++++++++++++
 .../docs/user-guide/features/voice-mode.md    |  2 +
 2 files changed, 80 insertions(+)

diff --git a/website/docs/user-guide/docker.md b/website/docs/user-guide/docker.md
index 9456acb21f3..381e5da757d 100644
--- a/website/docs/user-guide/docker.md
+++ b/website/docs/user-guide/docker.md
@@ -238,6 +238,84 @@ services:
 
 Start with `docker compose up -d` and view logs with `docker compose logs -f`. Dashboard output is prefixed with `[dashboard]` so it's easy to filter from gateway logs.
 
+## Optional: Linux desktop audio bridge
+
+Voice mode in Docker needs two separate things to work: Hermes must be allowed to probe audio devices inside the container, and the container must be able to reach your host audio server. The setup below covers the host audio plumbing for Linux desktops that expose a PulseAudio-compatible socket, including many PipeWire setups.
+
+:::caution
+This is a Linux desktop workaround, not a general Docker Desktop feature. It is useful when you already have host audio working and want CLI voice mode inside the Hermes container. If Hermes still reports `Running inside Docker container -- no audio devices`, use a build that includes Docker audio probing support for `PULSE_SERVER` / `PIPEWIRE_REMOTE`.
+:::
+
+First, create an ALSA config next to your Compose file:
+
+```conf title="asound.conf"
+pcm.!default {
+    type pulse
+    hint {
+        show on
+        description "Default ALSA Output (PulseAudio)"
+    }
+}
+
+pcm.pulse {
+    type pulse
+}
+
+ctl.!default {
+    type pulse
+}
+```
+
+Then build a small derived image with the ALSA PulseAudio plugin installed:
+
+```dockerfile title="Dockerfile.audio"
+FROM nousresearch/hermes-agent:latest
+
+USER root
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libasound2-plugins \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+Use that image in Compose and pass through the host user's PulseAudio socket and cookie:
+
+```yaml
+services:
+  hermes:
+    build:
+      context: .
+      dockerfile: Dockerfile.audio
+    image: hermes-agent-audio
+    container_name: hermes
+    restart: unless-stopped
+    command: gateway run
+    volumes:
+      - ~/.hermes:/opt/data
+      - /run/user/${HERMES_UID}/pulse:/run/user/${HERMES_UID}/pulse
+      - ~/.config/pulse/cookie:/tmp/pulse-cookie:ro
+      - ./asound.conf:/etc/asound.conf:ro
+    environment:
+      - HERMES_UID=${HERMES_UID}
+      - HERMES_GID=${HERMES_GID}
+      - XDG_RUNTIME_DIR=/run/user/${HERMES_UID}
+      - PULSE_SERVER=unix:/run/user/${HERMES_UID}/pulse/native
+      - PULSE_COOKIE=/tmp/pulse-cookie
+```
+
+Start it with your host UID/GID so the container process can access the per-user audio socket:
+
+```sh
+export HERMES_UID="$(id -u)"
+export HERMES_GID="$(id -g)"
+docker compose up -d --build
+```
+
+To verify what PortAudio sees inside the container:
+
+```sh
+docker exec hermes /opt/hermes/.venv/bin/python -c "import sounddevice as sd; print(sd.query_devices())"
+```
+
 ## Resource limits
 
 The Hermes container needs moderate resources. Recommended minimums:
diff --git a/website/docs/user-guide/features/voice-mode.md b/website/docs/user-guide/features/voice-mode.md
index ead50fe7c4c..fff3eaa808f 100644
--- a/website/docs/user-guide/features/voice-mode.md
+++ b/website/docs/user-guide/features/voice-mode.md
@@ -485,6 +485,8 @@ brew install portaudio    # macOS
 sudo apt install portaudio19-dev  # Ubuntu
 ```
 
+If you are running Hermes inside Docker on a Linux desktop, the container also needs access to your host audio socket. See the [Docker audio bridge](/user-guide/docker#optional-linux-desktop-audio-bridge) notes for a PulseAudio/PipeWire-compatible setup.
+
 ### Bot doesn't respond in Discord server channels
 
 The bot requires an @mention by default in server channels. Make sure you: