OmniVoice in Docker

OmniVoice in Docker

Give complete instuctions on how to Deploy OmniVoice in Docker on MX25 Linux. I already have nvidia-container-toolkit on my machine.

To be done: Configure remote access across local network

Gemini

MX25 Linux (Debian-based) with the nvidia-container-toolkit already configured requires confirming GPU accessibility in Docker before running OmniVoice Studio (the full web UI) or OmniVoice-FastAPI (headless API server).

1

Verify NVIDIA Docker Runtime

Ensures Docker can access your GPU on MX Linux

Run a quick CUDA test container to ensure Docker communicates properly with your NVIDIA driver:

docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

If this prints your GPU details, proceed. If it fails, ensure your current user is in the docker group (sudo usermod -aG docker $USER) and restart the Docker service (sudo systemctl restart docker).

2

Deploy OmniVoice Studio (Web UI)

Option A: Full Interface Setup

To run OmniVoice Studio with GPU acceleration, persistent data, and shared HuggingFace cache:

docker run -d \
  --name omnivoice \
  --gpus all \
  --restart unless-stopped \
  -p 127.0.0.1:3900:3900 \
  -v omnivoice-data:/app/omnivoice_data \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/debpalash/omnivoice-studio:latest

Note: To access the UI from another device on your local network instead of just localhost, change -p 127.0.0.1:3900:3900 to -p 0.0.0.0:3900:3900.

3

Deploy OmniVoice OpenAI API (Alternative)

Option B: Headless API Setup

If you only need an OpenAI-compatible Speech/TTS endpoint (e.g., for local LLM pipelines like SillyTavern or Open-WebUI):

docker run -d \
  --name omnivoice-api \
  --gpus all \
  --restart unless-stopped \
  -p 8880:8880 \
  -v omnivoice_models:/app/models \
  diogod2r/omnivoice-fastapi:latest

4

Monitor Model Downloads

First-run setup requirement

On initial startup, OmniVoice downloads model weights (~2.4 GB to 4 GB). Track progress using the container logs:

# For Studio UI
docker logs -f omnivoice

# For API Endpoint
docker logs -f omnivoice-api

5

Access the Service

Once the download completes:

  • OmniVoice Studio UI: Open http://localhost:3900 in your browser.
  • OmniVoice API Docs: Open http://localhost:8880/docs in your browser.

You

garyrust@MX25-GPU-win:~

$ docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

Unable to find image 'nvidia/cuda:12.0.0-base-ubuntu22.04' locally

12.0.0-base-ubuntu22.04: Pulling from nvidia/cuda

aece8493d397: Already exists

cb5efdcf30fe: Pull complete

6c0deaabac71: Pull complete

56cb4663b3f5: Pull complete

0a0d0d55d972: Pull complete

Digest: sha256:4e9da312e1f5affc0ab1b2cb3f1141e163849dcd850d66fe315138e82e85427d

Status: Downloaded newer image for nvidia/cuda:12.0.0-base-ubuntu22.04

Wed Aug 26 14:15:15 2026

+-----------------------------------------------------------------------------------------+

| NVIDIA-SMI 580.173.02 Driver Version: 580.173.02 CUDA Version: 13.0 |

+-----------------------------------------+------------------------+----------------------+

| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |

| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |

| | | MIG M. |

|=======================================+====================+====================|

| 0 NVIDIA GeForce RTX 4070 Off | 00000000:01:00.0 On | N/A |

| 0% 49C P8 10W / 200W | 635MiB / 12282MiB | 30% Default |

| | | N/A |

+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+

| Processes: |

| GPU GI CI PID Type Process name GPU Memory |

| ID ID Usage |

|=========================================================================================|

| No running processes found |

+-----------------------------------------------------------------------------------------+

garyrust@MX25-GPU-win:~

$

Gemini

Your NVIDIA runtime is working properly—Docker has full access to your RTX 4070 (12 GB VRAM).

Proceed with deploying OmniVoice Studio:

docker run -d \
  --name omnivoice \
  --gpus all \
  --restart unless-stopped \
  -p 127.0.0.1:3900:3900 \
  -v omnivoice-data:/app/omnivoice_data \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/debpalash/omnivoice-studio:latest

1. Monitor Model Downloads

The image will start, but it needs to download model checkpoints on first boot. Stream the container logs to check progress:

docker logs -f omnivoice

(Press Ctrl + C to exit log streaming once you see the server finish loading.)

2. Access the Application

Once the logs indicate the web server is running, open your browser and navigate to:

http://localhost:3900

You

garyrust@MX25-GPU-win:~

$ docker logs -f omnivoice

INFO: Started server process [1]

INFO: Waiting for application startup.

2026-08-26 14:23:02,153 INFO [omnivoice.api] Startup watchdog armed: thread dump if startup exceeds 300s (#632).

INFO: Application startup complete.

INFO: Uvicorn running on http://0.0.0.0:3900 (Press CTRL+C to quit)

2026-08-26 14:23:02,200 INFO [omnivoice.api] Published 1 media-tool directory on PATH so dependencies can find ffmpeg/ffprobe (#1256)

2026-08-26 14:23:03,172 INFO [omnivoice.hf_progress] hf_progress: installed tqdm patch on huggingface_hub.utils.tqdm

2026-08-26 14:23:03,449 INFO [omnivoice.setup.models] Loaded 36 models from /app/backend/config/models.yaml

2026-08-26 14:23:03,591 INFO [omnivoice.model] downloads: Xet disabled → legacy LFS (hf_xet 1.6.0 installed=True), high_perf=False

2026-08-26 14:23:03,932 INFO [omnivoice.mcp] MCP app mounted at /mcp

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.schemas

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.tables

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.types

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.constraints

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.defaults

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.comments

2026-08-26 14:23:04,259 INFO [alembic.runtime.plugins] setup plugin alembic.autogenerate.checkconstraint_byname

2026-08-26 14:23:04,282 INFO [omnivoice.db.backup] Pre-migration DB backup written: /root/.omnivoice/omnivoice.db.backup-0.5.0-1 (0.2 MB)

2026-08-26 14:23:04,292 INFO [alembic.runtime.migration] Context impl SQLiteImpl.

2026-08-26 14:23:04,292 INFO [alembic.runtime.migration] Will assume non-transactional DDL.

2026-08-26 14:23:04,296 INFO [alembic.runtime.migration] Running upgrade -> 0001_phase1_settings, Phase 1: settings table for encrypted HF token persistence

2026-08-26 14:23:04,297 INFO [alembic.runtime.migration] Running upgrade 0001_phase1_settings -> 0002_voice_profile_demo_fields, Phase 3: voice_profile description + is_demo columns

2026-08-26 14:23:04,299 INFO [alembic.runtime.migration] Running upgrade 0002_voice_profile_demo_fields -> 0003_voice_profile_consent, Parity program Wave 0.2: consent-locked voice profiles

2026-08-26 14:23:04,299 INFO [alembic.runtime.migration] Running upgrade 0003_voice_profile_consent -> 0004_mcp_client_bindings, Parity program Wave 2.2: per-agent MCP voice bindings

2026-08-26 14:23:04,300 INFO [alembic.runtime.migration] Running upgrade 0004_mcp_client_bindings -> 0005_unified_profiles, Voice Studio unification: profile `kind` discriminator + design params

2026-08-26 14:23:04,301 INFO [alembic.runtime.migration] Running upgrade 0005_unified_profiles -> 0006_strip_object_object_instruct, Heal voice_profiles.instruct poisoned with the "[object Object]" sentinel.

2026-08-26 14:23:04,302 INFO [alembic.runtime.migration] Running upgrade 0006_strip_object_object_instruct -> 0007_rebuild_poisoned_design_instruct, Rebuild design-profile instructs poisoned with prose / "[object Object]".

2026-08-26 14:23:04,303 INFO [alembic.runtime.migration] Running upgrade 0007_rebuild_poisoned_design_instruct -> 0008_pronunciation_dictionary, Expressive-TTS Spec 01 Phase 1: user pronunciation dictionary

2026-08-26 14:23:04,303 INFO [alembic.runtime.migration] Running upgrade 0008_pronunciation_dictionary -> 0009_generation_history_starred, Generation takes: starred flag on generation_history

2026-08-26 14:23:04,304 INFO [alembic.runtime.migration] Running upgrade 0009_generation_history_starred -> 0010_remote_worker_schema, Remote worker control-plane schema.

2026-08-26 14:23:04,309 INFO [core.onboarding] 🎉 Seeded demo voice profile 'VoiceStudio Demo Voice'

2026-08-26 14:23:04,535 INFO [omnivoice.model] Preload skipped: k2-fsa/OmniVoice is not installed locally — the model will load (and download if requested) on first use.

2026-08-26 14:23:04,535 INFO [mcp.server.streamable_http_manager] StreamableHTTP session manager started

2026-08-26 14:23:04,535 INFO [omnivoice.api] MCP server mounted at /mcp

2026-08-26 14:23:04,641 INFO [omnivoice.api] Deferred startup complete — all routes live.

INFO: 127.0.0.1:38038 - "GET /health HTTP/1.1" 200 OK

2026-08-26 14:23:34,624 INFO [omnivoice.model] GPU pool sized to 2 worker(s) — 10.8 GB free / 5.0 GB per job (cap 4)

2026-08-26 14:23:35,044 WARNING [core.cudnn8] CTranslate2 ASR engines unavailable: CUDA is active but libcudnn_ops_infer.so.8 cannot be loaded (libcudnn_ops_infer.so.8: cannot open shared object file: No such file or directory). WhisperX and faster-whisper are CTranslate2, which requires cuDNN 8; loading it is not optional and its absence aborts the backend process outright rather than raising (#1371). Reinstall the compat libraries with `uv pip install --target <venv>/lib/pythonX.Y/site-packages/cudnn8_compat nvidia-cudnn-cu12==8.9.7.29`, or pin a non-CTranslate2 engine with OMNIVOICE_ASR_BACKEND=pytorch-whisper.

2026-08-26 14:23:35,044 INFO [omnivoice.api] Capture ASR backend selected: pytorch-whisper

2026-08-26 14:23:39,628 INFO [omnivoice.watermark] Watermark prefetch skipped: AudioSeal checkpoint is not cached

INFO: 127.0.0.1:38092 - "GET /health HTTP/1.1" 200 OK

Gemini

Your OmniVoice Studio container initialized successfully and automatically configured your VRAM allocations (GPU pool sized to 2 worker(s) on your RTX 4070).

You can now open your browser and navigate to:

http://localhost:3900

Container Health & Runtime Summary

  • Database & Initialization: Migrations complete, schema seeded, and API routes are live (GET /health 200 OK).
  • VRAM Allocation: OmniVoice recognized your ~12 GB VRAM and automatically allocated 2 concurrent GPU workers (~5.0 GB per job).
  • Automatic ASR Fallback: The backend detected that cuDNN 8 isn't present in the image and cleanly auto-switched to pytorch-whisper for speech recognition, avoiding any startup crashes.
  • First Generation Note: On your very first text-to-speech request via the web UI, k2-fsa/OmniVoice will download its model checkpoints directly to your mounted HuggingFace cache (~/.cache/huggingface).

Gemini

You're at the setup screen! To complete initialization and start using the interface, follow these two quick steps:

1. Trigger the Required Model Download Click the Download button on the far right of the first listed item:

  • VoiceStudio TTS (k2-fsa/OmniVoice, 600+ languages, zero-shot) REQUIRED (2.4 GB)

(Optional: If you want faster download speeds from Hugging Face, paste a free Hugging Face User Access Token into the field at the bottom before clicking Download.)

2. Proceed to Studio Interface Once the ~2.4 GB download finishes, the bottom right button (Waiting for required models...) will change to an active button allowing you to enter the main studio.

None of the extra models (Whisper, VoxCPM2, CosyVoice, etc.) are mandatory right now—you can download those later from the Settings menu as needed.

Gemini

Select Read at the top or click the Read-Only preset.

Quick Steps:

  1. Token type: Click Read (next to Fine-grained), or keep Fine-grained and click the Read-Only button under Presets.
  2. Token name: Type anything simple (e.g., omnivoice).
  3. Click Create token at the bottom left.
  4. Copy the generated string starting with hf_... and paste it into the token field in VoiceStudio to bypass download rate limits.

Gemini

Skip the token setup entirely—it isn't required to download the main weights.

  1. Bypass the Token: Clear out the token input field or ignore the error message completely.
  2. Start the Download: Click the Download button next to VoiceStudio TTS (k2-fsa/OmniVoice) at the top of the model list.
  3. Wait for Completion: Watch the progress bar in the UI (or monitor docker logs -f omnivoice in your terminal). Once finished, the button at the bottom right will unlock so you can enter VoiceStudio.

(If you ever need faster speeds later, you can add your Hugging Face token inside Settings → Credentials after entering the main dashboard.)

Gemini

The required model download is complete!

Click the pink Required models ready — continue button at the bottom right corner of your screen to open the main VoiceStudio workspace and start generating speech.

Gemini

Click No thanks (or Yes, share anonymous stats if you prefer).

Either choice takes you straight to the main UI—this is just a one-time privacy opt-in for usage analytics.

Gemini

Scroll down to the bottom of the page and click Finish, Done, or Launch Studio.

This screen is just an onboarding demo for speech-to-text dictation. If you don't see a finish button at the bottom, click the VoiceStudio logo at the top left to jump directly to the main dashboard.

You

I don't like dark color

Gemini

To switch to a light theme in VoiceStudio:

  1. Click the Settings icon (gear symbol) in the lower-left sidebar menu.
  2. Select the Appearance or General tab.
  3. Change the Theme toggle from Dark to Light (or System).

(Note: First click No thanks on that small popup box in the middle of your screen so it clears out of the way.)

Gemini

VoiceStudio currently only provides accent options under Color theme (pink, blue, purple, etc.) without a native Light/Dark toggle.

Since the UI hardcodes dark mode, use a browser extension to invert the workspace into a clean light background:

  • Firefox: Install Dark Reader, then toggle it to Light mode specifically for 127.0.0.1.
  • Chrome/Brave: Turn on the built-in auto-dark flag by navigating to chrome://flags/#enable-force-dark and setting it to Enabled with selective image inversion, or use the Dark Reader extension set to Light.

You

I don't want dark

Gemini

That Chrome flag only forces sites into dark mode, so it won't help here.

The easiest, cleanest way to turn VoiceStudio light is using the Dark Reader browser extension:

  1. Install the Dark Reader extension from your browser's extension store (Chrome Web Store / Firefox Add-ons).
  2. Click the extension icon while viewing the VoiceStudio tab.
  3. Switch the top toggle from Dark to Light.

This will invert VoiceStudio into a bright, white background theme with proper dark text contrast.

Gemini

Dark Reader is 100% free on desktop—that $9.99 prompt is just an optional donation request.

You don't need to pay anything. Here is how to use it right now:

  1. Look at the top right of your browser (next to the address bar) for the Puzzle Piece icon (Extensions).
  2. Click it, find Dark Reader, and click on it to open its panel.
  3. At the top of the popup, switch the mode from Dark to Light.
  4. Go back to your VoiceStudio tab ([http://127.0.0.1:3900](http://127.0.0.1:3900)), and the background will be converted to light mode.

You

didn't work

Gemini

Dark Reader fails on this interface because VoiceStudio's CSS explicitly marks all elements with hardcoded background variables.

You can instantly override the theme to pure white using your browser's Developer Console:

Step 1: Open Developer Tools

Press F12 (or Ctrl + Shift + I) on your keyboard while viewing the VoiceStudio tab.

Step 2: Paste and Run the Light Theme Fix

Click the Console tab at the top of the panel that opens, paste the following code, and press Enter:

document.body.style.cssText = "filter: invert(1) hue-rotate(180deg) !important; background: white !important;";

This immediately flips the dark background to bright white and reverses text colors to readable dark tones.

(Note: If you refresh the browser page, you will just need to hit Up Arrow + Enter in the Console tab to re-apply it.)

You

Configure remote access across local network

Gemini

To access VoiceStudio from other computers, phones, or tablets on your local network (LAN) instead of just your local host (127.0.0.1), update your Docker deployment to bind to all network interfaces (0.0.0.0).

Step 1: Find Your MX Linux Local IP Address

Open a terminal on your host machine and run:

hostname -I | awk '{print $1}'

(Take note of your IP address, e.g., 192.168.1.150.)

Step 2: Re-run the Container Bound to All Interfaces

Stop and remove your existing local container:

docker stop omnivoice && docker rm omnivoice

Relaunch the container with -p 0.0.0.0:3900:3900 (instead of 127.0.0.1):

docker run -d \
  --name omnivoice \
  --gpus all \
  --restart unless-stopped \
  -p 0.0.0.0:3900:3900 \
  -v omnivoice-data:/app/omnivoice_data \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/debpalash/omnivoice-studio:latest

Step 3: Allow Firewall Access (If Applicable)

If UFW or the MX Linux firewall is active, allow incoming traffic on port 3900:

sudo ufw allow 3900/tcp

Step 4: Access VoiceStudio from Remote Devices

On any device connected to the same Wi-Fi/local network, open your web browser and navigate to:

http://<YOUR_HOST_IP>:3900 (e.g., [http://192.168.1.150:3900](http://192.168.1.150:3900))