Added in v0.18.0 · optional
Run a local VocaGateway from Vocalinux
Vocalinux can start VocaGateway, the self-hosted speech gateway in the Voca family, as a podman or docker container from its own Settings. It is a power-user path for people who want one transcription service shared by the desktop and a paired phone.
Gateway mode is not the on-device engine
With a local engine, audio is transcribed on this machine by Vocalinux itself. In gateway mode it is sent over HTTP to the gateway, even when that gateway runs on 127.0.0.1. If you point Vocalinux at a gateway on another machine, your audio leaves this machine for that endpoint. Keep it on a trusted LAN, an encrypted private network such as Tailscale, or HTTPS, and never expose port 8765 to the public internet. Enabling the gateway does not change the default engine; whisper.cpp stays on-device until you click Use this Gateway.
Where your audio goes
| Mode | Audio | Setup | Network |
|---|---|---|---|
| Local engine (default whisper.cpp) | Stays on this machine; transcribed in the app | Download a model once | None for transcription |
| Local VocaGateway on 127.0.0.1 | Sent over HTTP to the gateway container on this machine | podman or docker with Compose | Loopback only by default |
| Gateway or Remote API on another machine | Leaves this machine for the endpoint you configured | Server URL and token in Remote Server | Your LAN, VPN or the internet |
Requirements
- podman (preferred) or docker, with a working Compose plugin, or
podman-compose/docker-compose. If the engine is present but Compose is missing, Settings tells you which to install. - A native install or the AppImage. The AppImage does not bundle a container engine; it uses the host's podman or docker socket when available.
- Not the Flatpak: its sandbox cannot reach the host container socket, so the controls are blocked there.
Set it up
- 1
Open the Advanced section
Open Settings → Speech Model and expand Advanced. The Local VocaGateway group sits next to Remote Server.
- 2
Run the gateway
Click Run VocaGateway locally. The first start builds the local image vocagateway:v0.1.0 from the pinned tag, so it takes longer than later starts.
- 3
Wait for Ready
Watch the Status row. Select a model in the gateway's own web UI; the status shows Ready once the gateway reports it can transcribe.
- 4
Use this Gateway
Click Use this Gateway. Vocalinux fills Remote Server with the gateway URL and bearer token, sets the endpoint to /v1/audio/transcriptions and switches the engine to Remote API.
- 5
Dictate and verify
Use Test Connection in Remote Server, then dictate as usual with your normal shortcut.
Status labels
| Stopped | Not running. |
|---|---|
| Starting | Compose up in progress, or the live probe is not green yet. |
| Live | The gateway answers /health/live. |
| Pairable | Live, plus a non-loopback phone URL and bearer token for pairing. |
| Ready | /health/ready returns 200 (a model is selected in the gateway). |
| Error | Start, stop or probe failure; the subtitle says which. |
Pairable can appear before Ready, so a phone can pair while a model is still downloading.
What Vocalinux sets up
- A checkout of VocaGateway pinned to the
v0.1.0tag under your XDG cache, run as the Compose projectvocagatewaywith thecpuprofile. It never floats onlatest;VOCAGATEWAY_IMAGEoverrides the image. - A private bootstrap token in
~/.config/vocalinux/gateway_embed/with mode 600, plus a matching Compose.env. - A port published on
127.0.0.1:8765by default, reachable from this desktop only. - The usual Remote API settings. Use this Gateway writes the URL, token, endpoint and the model name
whisper-1into the sameremote_api_*keys described on the Remote API page. The token is stored in plain JSON inconfig.json, like any Remote API key.
LAN access, stopping and gotchas
Allow LAN access for Phone
This switch publishes the gateway on 0.0.0.0:8765 and advertises a LAN URL for phone pairing. Open port 8765 in your firewall only on networks you trust. If the switch fails, Compose keeps the previous bind and the switch snaps back with an error; stop and run again, or retry.
Quit does not stop it
The container keeps running after you quit Vocalinux, including a LAN-published one. Use Stop local Gateway in Settings or the tray menu, which appears whenever Compose is running. Stopping keeps the named data volume, so downloaded models survive. Vocalinux does not start the gateway on login.
Other machines
You can also run VocaGateway on a stronger box and enter its address in Remote Server by hand. Audio then crosses your network, so prefer a trusted LAN, Tailscale or HTTPS. Read the VocaGateway documentation for server-side setup.
FAQ
Is a local gateway the same as on-device dictation?
No. Even on 127.0.0.1, audio leaves the Vocalinux client and is transcribed by a separate gateway process over HTTP. The on-device path is a local engine such as whisper.cpp, which stays the default.
Does quitting Vocalinux stop the gateway?
No. The pinned compose file uses restart: unless-stopped, so the container keeps running after Quit. Use Stop local Gateway in Settings or the tray menu.
Can I run it from the Flatpak?
No. The Flatpak sandbox cannot reach the host podman or docker socket. Use the native package or AppImage, or start VocaGateway on the host yourself and point Remote Server at it.
Do I need a Voca account?
No. VocaGateway is optional self-hosted software. There is no Voca account and no hosted Voca cloud.
How do I go back to on-device transcription?
Choose a local engine again under Speech Engine in Settings → Speech Model → Advanced. Stop the gateway too if you no longer need it.
Related: offline dictation, privacy, Flatpak limitations and GPU acceleration for faster on-device engines.
Start on-device, add a gateway later
Install Vocalinux with the default on-device engine. Add a local VocaGateway only if you need a shared transcription service.