Self-host VoiceStudio

Create a VM#

The VoiceStudio image is big (about 17 GB on disk, with PyTorch and CUDA libraries inside), so give the VM a 60 GB disk. You're billed for the disk you use, not its size. On your computer (pick another name if my-voicestudio is taken):

ssh exe.dev new --name=my-voicestudio --disk=60GB
ssh my-voicestudio.exe.xyz

All remaining installation commands run on the VM, as exedev. Commands use hostname, so your VM can have any name.

Room on the disk#

Check the disk:

df -h /

If Size is under 54G, the VM was made with a smaller disk. Grow it with this link (with your VM's name), or on your computer with ssh exe.dev resize my-voicestudio --disk=60GB. Then, back on the VM, grow the filesystem to match:

sudo resize2fs "$(findmnt -no SOURCE /)"
df -h /

Expect a size of about 59G.

Get Docker ready#

Enable Docker at boot, or exe.dev's on-demand Docker won't restart VoiceStudio after a reboot. Install jq if needed:

sudo systemctl enable --now docker.service
systemctl is-enabled docker.service
command -v jq >/dev/null || sudo apt-get install -y jq

The check should print enabled.

Start VoiceStudio#

This writes .env once, with a random API key, then a Compose file. The image listens on port 3900; Compose publishes it on port 8000, which exe.dev's proxy serves at https://<vm>.exe.xyz/. Everything VoiceStudio keeps, including the models it downloads, goes in ~/voicestudio/data.

mkdir -p ~/voicestudio/data
cd ~/voicestudio
if [ ! -e .env ]; then
  touch .env && chmod 600 .env
  echo "OMNIVOICE_API_KEY=$(openssl rand -hex 32)" >> .env
fi
cat > compose.yaml <<EOF
# VoiceStudio behind exe.dev's HTTPS proxy, on CPU.
# The API key comes from .env in this directory.
name: voicestudio

services:
  voicestudio:
    # 0.5 follows the newest 0.5.x release.
    image: ghcr.io/debpalash/voicestudio:0.5
    restart: unless-stopped
    ports:
      - "8000:3900"
    env_file: .env
    environment:
      # Keep voices, projects and settings in ./data. Without this they
      # live inside the container and vanish when it is recreated.
      OMNIVOICE_DATA_DIR: /app/omnivoice_data
      # Never send usage statistics.
      OMNIVOICE_ANALYTICS_DISABLED: "1"
      # Let MCP clients in through https://$(hostname).exe.xyz/mcp/.
      OMNIVOICE_MCP_ALLOWED_HOSTS: $(hostname).exe.xyz
    volumes:
      - ./data:/app/omnivoice_data
EOF

Pull the image (about 6 GB to download, several minutes) and start it:

cd ~/voicestudio
docker compose pull
docker compose up -d
until curl -fs http://localhost:8000/health; do sleep 5; done; echo
docker compose ps

Expect {"status":"ok","device":"cpu","version":"0.5.…"}, and the container Up, and healthy after a minute or two.

Check speech#

Without the key, VoiceStudio refuses. This should print 401:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/engines

Then, with the key, download two small models: KittenTTS (80 MB, Apache-2.0) for speech, and Whisper base (150 MB, MIT) for transcription. Wait until both are installed:

cd ~/voicestudio
auth="Authorization: Bearer $(sed -n 's/^OMNIVOICE_API_KEY=//p' .env)"
for repo in KittenML/kitten-tts-mini-0.8 Systran/faster-whisper-base; do
  curl -fsS -X POST http://localhost:8000/models/install -H "$auth" \
    -H 'Content-Type: application/json' -d "{\"repo_id\":\"$repo\"}"; echo
  until curl -fsS http://localhost:8000/models -H "$auth" | jq -e --arg r "$repo" \
    '.models[] | select(.repo_id == $r) | .installed' >/dev/null
  do sleep 5; done
done

Expect install_started twice. VoiceStudio's default transcription model is a 2.9 GB Whisper it hasn't downloaded, so make Whisper base the active one:

auth="Authorization: Bearer $(sed -n 's/^OMNIVOICE_API_KEY=//p' ~/voicestudio/.env)"
curl -fsS -X POST http://localhost:8000/engines/select -H "$auth" \
  -H 'Content-Type: application/json' \
  -d '{"family":"asr","backend_id":"faster-whisper","model_id":"Systran/faster-whisper-base"}'; echo

Expect "active":"faster-whisper". Now have KittenTTS say a sentence, and Whisper write it back down:

auth="Authorization: Bearer $(sed -n 's/^OMNIVOICE_API_KEY=//p' ~/voicestudio/.env)"
curl -fsS http://localhost:8000/v1/audio/speech -H "$auth" \
  -H 'Content-Type: application/json' \
  -d '{"model":"kittentts","voice":"alloy","input":"The quick brown fox jumps over the lazy dog.","response_format":"wav"}' \
  -o /tmp/hello.wav
file /tmp/hello.wav
curl -fsS http://localhost:8000/v1/audio/transcriptions -H "$auth" \
  -F file=@/tmp/hello.wav -F model=whisper-1; echo
rm /tmp/hello.wav

Expect RIFF (little-endian) data, WAVE audio, ... mono 24000 Hz, then {"text":"The quick brown fox jumps over the lazy dog."}. The default voice model, OmniVoice, waits for the owner to accept its licence in the studio.

Set up nightly backups#

The backup stops VoiceStudio for a few seconds, so its database is copied in a consistent state. It runs as root because the container writes data as root, and skips data/huggingface, the downloaded models.

cat > ~/voicestudio/backup.sh <<'EOF'
#!/usr/bin/env bash
# Back up VoiceStudio: data (voices, projects, history, settings) without
# the downloadable models, .env (the API key), and the Compose file.
# Run with sudo.
set -euo pipefail
umask 077
cd "$(dirname "$(readlink -f "$0")")"
owner=$(stat -c %U:%G .)
dest="$(dirname "$PWD")/voicestudio-backups"
mkdir -p "$dest"
out="$dest/voicestudio-$(date -u +%Y%m%d-%H%M%S).tar.gz"

# A short stop keeps the SQLite database consistent.
docker compose stop voicestudio
trap 'docker compose start voicestudio' EXIT
tar -czf "$out.part" --exclude=data/huggingface .env compose.yaml backup.sh data
docker compose start voicestudio
trap - EXIT
mv "$out.part" "$out"
chown -R "$owner" "$dest"

# Keep the 14 newest backups.
ls -1t "$dest"/voicestudio-*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/voicestudio/backup.sh

Schedule it for 03:30 UTC (or so), then take a first backup:

sudo tee /etc/systemd/system/voicestudio-backup.service >/dev/null <<EOF
[Unit]
Description=Back up VoiceStudio to ~/voicestudio-backups
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
ExecStart=$HOME/voicestudio/backup.sh
EOF
sudo tee /etc/systemd/system/voicestudio-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up VoiceStudio every night

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now voicestudio-backup.timer
sudo systemctl start voicestudio-backup.service
systemctl list-timers voicestudio-backup.timer
ls -lh ~/voicestudio-backups
until curl -fs http://localhost:8000/health; do sleep 5; done; echo

Check that the timer has a next run, the directory has a tarball of a few hundred KB (more once you have voices), and VoiceStudio is back. For failures: journalctl -u voicestudio-backup.service.

Test a backup#

Unpack the newest backup into a scratch directory and check its database, without touching the running copy:

latest=$(ls -1t ~/voicestudio-backups/voicestudio-*.tar.gz | head -n 1)
mkdir /tmp/voicestudio-restore-test
sudo tar -xzf "$latest" -C /tmp/voicestudio-restore-test
sudo ls -A /tmp/voicestudio-restore-test /tmp/voicestudio-restore-test/data
sudo python3 -c '
import sqlite3
db = sqlite3.connect("file:/tmp/voicestudio-restore-test/data/omnivoice.db?mode=ro", uri=True)
print(db.execute("pragma integrity_check").fetchone()[0])
print("voices", db.execute("select count(*) from voice_profiles").fetchone()[0])
'
sudo rm -rf /tmp/voicestudio-restore-test

Expect .env, compose.yaml, backup.sh and data (with omnivoice.db and no huggingface), then ok and the number of saved voices.

Installation done. Continue with Open the studio.

On the VM, sudo ~/voicestudio/backup.sh makes an extra backup and prints its path. Copy backups off the VM as shown in Keep your voices.

Restore#

On a new VM, follow Install up to and including Get Docker ready. Create ~/voicestudio-backups there, then copy your backup over from your computer:

scp voicestudio-20261030-033012.tar.gz my-voicestudio.exe.xyz:voicestudio-backups/

Use your backup's actual filename in this and the commands below. All remaining commands run on the VM. If VoiceStudio already runs there, stop it and keep its directory aside first:

cd ~/voicestudio && docker compose down
sudo mv ~/voicestudio ~/voicestudio.before-restore

Unpack the backup, point MCP at this VM's name, and start it:

mkdir ~/voicestudio
sudo tar -xzf ~/voicestudio-backups/voicestudio-20261030-033012.tar.gz -C ~/voicestudio
cd ~/voicestudio
sed -i "s/^\( *OMNIVOICE_MCP_ALLOWED_HOSTS:\).*/\1 $(hostname).exe.xyz/" compose.yaml
docker compose up -d
until curl -fs http://localhost:8000/health; do sleep 5; done; echo

Sign in with the API key from the backup and check your voices are there. The models aren't in the backup: download KittenTTS and Whisper base again with the first block in Check speech, and the rest from Settings → Models. On a new VM, recreate the backup timer from Install. Keep ~/voicestudio.before-restore until you're happy everything is back.

The 0.5 image tag follows the newest 0.5.x release. On the VM, back up, then pull and restart:

cd ~/voicestudio
sudo ./backup.sh
docker compose pull
docker compose up -d
until curl -fs http://localhost:8000/health; do sleep 5; done; echo
docker image prune -f
df -h /

The health check shows the new version. The prune frees the old image's disk space; until then, both images are on disk, which is why the VM has 60 GB. Sign in to the studio again after the restart.

For a new minor version, such as 0.6, read the release notes first, then change the image: tag in compose.yaml and run the same commands. VoiceStudio upgrades its database on start and keeps a copy of the old one in data; to roll back fully, restore the backup.

On the VM:

cd ~/voicestudio
docker compose ps
docker compose logs --tail=100 voicestudio

• 502 right after starting or updating: VoiceStudio takes a minute to load. Wait for curl -fsS http://localhost:8000/health.
• The studio asks for the API key again: sessions end after eight hours and whenever VoiceStudio restarts, including during the nightly backup. Paste the key from ~/voicestudio/.env.
• "This model can't be used until you accept its licence": open the licence dialog when you synthesize and accept it, or select another engine such as KittenTTS under Settings → Models → TTS.
• "No speech-to-text model is installed": under Settings → Models → ASR, select a Whisper model marked installed, or download one.
• A generation times out: CPU synthesis of long scripts is slow. Split the script, use KittenTTS, or give the VM more CPUs with ssh exe.dev resize.
• MCP says Invalid Host header: the VM was renamed or restored on another VM. Set OMNIVOICE_MCP_ALLOWED_HOSTS in compose.yaml to the current <vm>.exe.xyz and run docker compose up -d.
• Down after a reboot: run sudo systemctl enable --now docker.service.
• Disk full: check df -h / and sudo du -sh ~/voicestudio/data/huggingface. Run docker image prune -f, or grow the disk with ssh exe.dev resize.