soubarnak
ea7be5f111
The fork takes its own name everywhere a user can see it: binaries (voculinux, voculinux-gui), desktop entry, autostart, tray, D-Bus namespace (com.voculinux.Voculinux, no alias for the old name), config/data/cache dirs, single-instance lock, IBus engine identity, tray icons, resource prefixes, VOCULINUX_* environment names, and the update-checker user agent. The internal Python module stays vocalinux and the distribution metadata keeps the upstream URLs as provenance. On first run a previous Vocalinux install's config.json, custom dictionary, and portal restore token are copied once into the new locations (new config always wins, no merge, no write-back); models re-resolve through the pinned-checksum download path. An offline naming-sweep test proves no old-name strings remain on user-visible surfaces outside the allowlist. Refs #18
78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
# Local VocaGateway from Voculinux (optional)
|
|
|
|
Voculinux can start a **local** [VocaGateway](https://github.com/VocaHQ/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).
|
|
|
|
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](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.
|