xavierk
a4a831c3c6
The missing-dependency error gives the Void xbps instruction instead of piping upstream's installer, the IBus hint points at the fork's docs (niri names its own notes), and the IBus engine homepage is the fork. VocaGateway stays upstream, with the credit stated in code and docs.
81 lines
3.9 KiB
Markdown
81 lines
3.9 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).
|
|
|
|
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](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.
|