voculinux/docs/GATEWAY_EMBED.md

Local VocaGateway from Voculinux (optional)

Voculinux can start a local VocaGateway container from Settings → Speech Model → Advanced, next to Remote Server. This is an optional power-user path. It is not on-device processing: microphone audio still leaves the desktop client and is transcribed by the gateway process on your machine (or LAN).

VocaGateway is a separate upstream project by VocaHQ, not part of Voculinux. Voculinux does not publish it; the Settings action clones the pinned upstream tag.

The default speech engine remains whisper.cpp on-device. Enabling a local gateway never changes that default by itself. Use Use this Gateway only when you want Voculinux to talk to the gateway over the existing Remote API settings (remote_api_*, endpoint /v1/audio/transcriptions). See HTTP_REMOTE.md.

Requirements (Linux MVP)

• podman (preferred) or docker, with a working compose plugin (or podman-compose / docker-compose).
• Voculinux does not bundle a container engine inside the AppImage.
• Flatpak: the sandbox cannot reach the host container socket. Run the native package or AppImage, or start VocaGateway on the host yourself and point Remote Server at it.

What Voculinux does

1. Pins upstream VocaGateway v0.1.0 (git tag) under your XDG cache and uses that checkout's compose.yaml with Compose project name vocagateway.
2. Writes a private bootstrap token under ~/.config/voculinux/gateway_embed/ (mode 600) and a matching Compose .env.
3. Runs compose -f compose.yaml --profile cpu up -d for the gateway service. The v0.1.0 GitHub release has no published container image assets, so the first start builds the local image vocagateway:v0.1.0 from that tag (override with VOCAGATEWAY_IMAGE; never latest). Later starts reuse the image/volume.
4. Polls GET /health/live and GET /health/ready, and (when live) authenticated GET /v1/admin/pairing for phone pairing.
5. Stops with compose down without -v, so the named data volume (models, config) is kept.

Status labels

Status	Meaning
Stopped	Not running.
Starting	Compose up in progress, or live probe not green yet.
Live	Process answers /health/live.
Pairable	Live, plus a non-loopback phone URL and bearer token (QR-safe).
Ready	/health/ready is 200 (model selected in the gateway WebUI).
Error	Start/stop or probe failure (see the subtitle).

Pairable can appear before Ready: you can pair a phone while a model is still downloading.

LAN / phone

By default the published host is 127.0.0.1 (desktop-only). Turn on Allow LAN access for Phone to set VOCAGATEWAY_PUBLISH_HOST=0.0.0.0 and to advertise a LAN URL in pairing. Open port 8765 in your firewall only on trusted networks. Never put 127.0.0.1 / localhost in the phone QR. If a LAN toggle fails, compose keeps the previous bind, Voculinux restores the embed .env, and the switch snaps back with an error (Stop and Run again, or retry).

Tray and Quit

The tray menu offers Stop local Gateway whenever compose is actually running (Starting, Live, Pairable, Ready, or Error), including a leftover from a previous Voculinux session. Voculinux does not auto-start the gateway on login in v1.

Quit does not stop compose. The pinned compose file uses restart: unless-stopped, so a LAN-published gateway on 0.0.0.0:8765 keeps running after you quit Voculinux. The next launch restores the Allow LAN switch from the running compose publish host. Use Stop local Gateway in Settings or the tray when you want it gone. Do not assume Quit tears it down.

Honesty

VocaGateway is optional self-hosted infrastructure for the Voca family. There is no Voca account and no hosted Voca cloud. Prefer a trusted LAN, Tailscale, or HTTPS. Do not expose port 8765 to the public internet.