Installation — Mayva docs

macOS

Mayva is developed primarily on macOS. Voice is macOS-only today (depends on sox, say, afplay).

# Toolchain
brew install pnpm
brew install --cask docker        # or OrbStack, Colima
brew install sox                  # audio capture for voice
brew install whisper-cpp          # local STT, faster than openai-whisper

# Optional speedup on Apple Silicon
pip install mlx-whisper

pnpm voice tries whisper-cpp first, falls back to openai-whisper, then mlx-whisper. Whichever is on your $PATH.

Linux

Workers, dashboard, and core all run cleanly. Voice does not — the capture script uses sox (works) and say (Apple-only). You can substitute espeak-ng for TTS with a one-line patch to scripts/voice.ts.

# Debian / Ubuntu
sudo apt install sox espeak-ng
curl -fsSL https://get.pnpm.io/install.sh | sh

Windows

Workers and dashboard work via WSL2. Voice does not. Pull requests welcome.

Common installation issues

`pnpm install` fails on `electron`

Electron has a postinstall that downloads the prebuilt binary. If you’re behind a corporate proxy or your network blocks *.electronjs.org, set:

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
pnpm install

Postgres connection refused

Most likely the docker daemon isn’t running, or the port collides with a local Postgres. Check:

docker compose ps
docker compose logs postgres

If you have a system Postgres on :5432, edit docker-compose.yml to map to a different host port, then update DATABASE_URL in .env.

`whisper-cpp: command not found` after `pnpm voice`

Reopen the terminal so the brew shim is on $PATH, or check:

which whisper-cpp

Mayva looks for the binary by name. You can override with WHISPER_BIN=/abs/path/to/whisper.

Slow voice on Apple Silicon

Whisper.cpp uses the small.en model by default. If you have mlx-whisper installed and a recent M-series chip, set:

export VOICE_BACKEND=mlx

Roughly 3-4× faster transcription with similar quality.

Verifying the install

pnpm typecheck     # full repo, ~30s on a cold cache
pnpm test          # vitest, ~10s
pnpm pg:smoke      # boots a transient Postgres, runs migrations end-to-end

If all three pass, you have a working install. Open an issue if any fail with a clean checkout.