AIVG — AI Voice Gateway

AIVG is a platform-neutral voice satellite system: a thin, realtime voice transport (WebRTC / Opus) bridged into whichever agent platform plugin is configured (v1 canonical: Hermes; planned: OpenClaw). Satellites capture audio and play it back; STT, the agent loop, TTS, and end-of-utterance detection live in the upstream agent platform.

Install (PyPI)

pip install aivg

Supported: Python 3.11+ on Linux x86_64/aarch64, macOS arm64/x86_64.

⚠ Install into your existing Hermes virtualenv, not a fresh venv. The aivg-satellite entry point is only discoverable by Hermes's plugin loader if AIVG lives in the same venv Hermes runs from:

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python aivg

Then add aivg-satellite under plugins.enabled: in ~/.hermes/config.yaml and restart the gateway. Full setup flow: see docs/ or run aivg setup --help.

Repo: https://github.com/cloudomate/aivg · Changelog: CHANGELOG.md · License: MIT.

Status

Quickstart

pip install -e .          # picks up the renamed entry point
aivg --version            # JSON envelope, contract_version 0.3.0
aivg list                 # see the fleet
aivg device get kitchen   # full state of one device
aivg logs kitchen --follow
aivg onboard --ssid "MyWiFi" --password "..." --name "bedroom"

Repo layout

src/aivg_core/           # platform-neutral management plane
  platforms/hermes/        # v1 Hermes plugin (Hermes-platform agent skill, bridge)
  platforms/openclaw/      # planned plugin (stub)
  webrtc/                  # voice plane (WebRTC)
  transports/              # additive non-WebRTC transports
    esphome/                 # ESPHome native API (feature 017)
    grpc/                    # gRPC bidi streaming (feature 021)
  management/              # App. A REST + SSE + control WS
src/aivg_cli/            # `aivg` Typer CLI
proto/                   # canonical cross-language wire schemas (gRPC transport)
skills/hermes-agent/     # Hermes-platform agent skill (invokes `aivg` CLI)
specs/                   # Spec Kit features 001–021
docs/                    # design notes, data-dir reference, rebrand allow-list

Transports

A satellite's audio plane can run over any of three transports; the gateway selects the best one each satellite advertises (no flag-day, no per-device branching):

The gRPC transport is off by default. Opt in via the satellite: block in ~/.hermes/config.yaml:

satellite:
  enabled: true
  transports:
    grpc:
      enabled: true
      port: 8645              # audio plane (distinct from management 8643 / webrtc 8644)
      tls: insecure           # trusted-LAN default; "mtls" for fleet
      downstream_codec: pcm   # or "opus"
      management_over_grpc: false   # true => also serve the control plane over gRPC

The canonical wire schema lives at proto/aivg/satellite/v1/ — the single source of truth shared by the Python gateway and native C++ clients (in the companion aivg-devices repo). Regenerate the Python stubs with scripts/gen_proto.sh.

Hermes vs AIVG

Development

# Editable install with all dev deps (pytest, ruff, black, etc.)
pip install -e ".[dev]"
# or with uv:
uv pip install -e ".[dev]"

# Run the suite
pytest -q                 # 300+ tests

Runtime + dev deps are declared in pyproject.toml under [project] and [project.optional-dependencies] respectively. (The legacy requirements-dev.txt was removed in feature 018 — single source of truth is the pyproject.toml extras now.)

See specs/ for the design history and the active feature (currently 018-aivg-pypi-distribution).