on-air

On Air

On Air is a Hermes plugin that adds a guarded AI co-host to your stream.

A synthetic private practice scene showing the mascot and a caption at 1280×720.

What you get

• Guarded co-host replies with captions, optional voice and owner approval.
• A Live desk for reviewing replies, privacy, mute and Stop.
• Optional hands-free open mic to send your speech to the co-host without transcript review.
• Your typed and desk-microphone host lines take priority over unapproved filler and survive a cut-in; other safety cuts discard them.
• OBS Main and Sub box layouts by plain-language request, with window selection left to you.
• A text-only work view and a live-build skill for sharing selected code and tests with your own narration.
• An explained pause and a standby card when the stage pauses.

Quick start: private rehearsal

1. Install Hermes 0.22.7 or newer with its Python 3.14 runtime. Install and enable On Air:

   hermes plugins install https://github.com/HomunculusLabs/hermes-on-air --enable
   

2. Run the synthetic offline rehearsal. It uses canned chat and replies, not a model, Twitch or voice:

   hermes onair rehearse
   

3. For a model-backed private show, configure your owner model in an interactive terminal and start a new local Hermes session:

   hermes setup
   hermes
   

4. Ask your agent: “Set up On Air for example_channel. Rehearse privately with captions and let me approve each reply.” Give it your public show topic and co-host style. Keep credentials out of chat.

5. Review the setup plan, type its returned approval command yourself and confirm the card. Review the private preview.

6. Ask for a private show. Review its plan, type its returned approval command and confirm the card. Show or skip replies, then end the show. It uses your owner model and private typed chat, not Twitch.

See Quickstart for the full private-show steps, Streaming setup before going live, and Safety for the safety model.

Limits

The work view accepts text only, not images or arbitrary URLs. Live-build narration is not automatic: you supply the lines. Voice latency is measured in seconds, not real time. The Live desk controls the real stage only when the dashboard backend runs in the stage profile. Window sharing depends on your platform and OBS. Synthetic rehearsal does not test your model, voice, Twitch connection or readiness to go live.

What your agent gets

The first 15 tools belong to onair_setup; the other 9 belong to onair_present (24 tools in total). If an
explicit tool list hides them, enable the relevant toolsets with hermes tools. The packaged
skills are listed below. The owner slash commands include /onair-setup, /onair-stage, /onair-present and
/onair-broadcast. The CLI has hermes onair setup, scene, preflight, rehearse, status,
host, check-line, voice-test and report. The CLI's manual setup path is documented separately.

Skills pack

• on-air:first-stream: take a new show from setup to private rehearsal.
• on-air:setup: prepare, customize and check the co-host.
• on-air:produce: prepare slides, OBS and a rehearsal.
• on-air:live-build: build in public steps with owner-provided narration.
• on-air:views: arrange the three boxes and share a window safely.
• on-air:scene: create and preview the optional scene.
• on-air:scene-build: design an owner 3D room.
• on-air:avatar: use and check a licensed VRM.
• on-air:host: send host lines and use the talk controls safely.
• on-air:show-day: run the show-day checklist.
• on-air:troubleshoot: diagnose failures and report uncertainty.
• on-air:seed-bank: interview the owner and prepare a public rundown.

The skills are registered in owner homes, not stage homes. Owner tools refuse messaging
surfaces that cannot establish owner identity.

What stays yours

• Review plans and type approval commands yourself, then confirm the host card. Safety stops do
  not require approval. Only you resume a private show or arm the stage.
• Choose when to go live. The agent can request a broadcast start, but you type the returned
  /onair-broadcast start <code> and confirm it. OBS reports whether output actually started.
• Choose the window in OBS or the system dialog. On Wayland, inspect the preview and confirm
  /onair-broadcast confirm-window yourself; the software cannot verify the selected capture.
• Configure model access using the stage home's own hermes model. Set the OBS WebSocket
  password through ONAIR_OBS_PASSWORD; do not give credentials to the agent in chat.

How it stays safe

• Setup creates a separate stage home with memory, user profile and context files disabled. It
  is a separate configuration, not an OS sandbox: processes still run as your user.
• Preflight requires platform_toolsets.on_air: [no_mcp]. An empty list is not equivalent:
  globally enabled MCP servers may still load. The llm_execution middleware rejects stage
  requests carrying tools or memory context; the pre_llm_call hook skips inference off air.
• A deterministic output guard checks lines before captions and speech; a word filter blocks
  slurs and applies the configured profanity policy. These are fallible backstops, not a
  prompt-injection boundary or a replacement for human moderation.
• The real stage starts off air and arms into approval mode. Privacy, mute, off-air and stop
  controls are separate; a stop or off-air request is not confirmation unless the result says so.
• Network listeners bind to loopback. Control APIs use bearer tokens; the display pages themselves
  are not token-authenticated. See Disclosure before relying on local isolation.

What this plugin can reach

• Network: Twitch IRC, the selected Hermes model, speech-to-text and text-to-speech providers,
  optional TypeSafe Jev or loopback Laya, loopback OBS and display/control APIs, and npm for the
  optional scene scaffold. Hermes installation can contact Git and package services.
• Files outside plugin data: selected stage-home configuration, persona and seed bank; installed
  plugin and process metadata; an operator-selected new OBS configuration root and scene directory.
• Commands: approved stage setup starts Hermes CLI commands and the stage process; optional
  development and verification tools start subprocesses. See Processes and jobs below.
• Background processes: an approved stage runs a separate Hermes process; previews, shows and
  presentation use background threads. Local display pages are not authenticated.
• Stored credentials: Hermes manages model and plugin credentials; On Air stores local control
  bearer tokens in its plugin data and writes a nonsecret stage sender file during setup.

Disclosure

Network and data sent. When the real stage is connected, Twitch chat is read over TLS from
irc.chat.twitch.tv:6697 using an anonymous, read-only IRC login. Model requests go through your
configured Hermes provider; opting into model-backed setup includes a small liveness request before
planning, and private preview can make a further model request. Private show and real stage can make
more. Voice sends released text through Hermes text-to-speech and its configured provider. Optional
hold-to-talk and owner-activated open mic send owner audio to the configured Hermes speech-to-text
provider, which may be cloud-hosted. Open mic sends detected transcripts to the host queue without
review; it is disabled by default and has a separate setting. See Talk. OBS control
connects to a loopback WebSocket, default
ws://127.0.0.1:4455. Optional semantic assistance is off by default: Laya uses a configured
loopback HTTP endpoint (default http://127.0.0.1:8390); Jev uses
https://api.typesafe.ai/v1/systemone. Assistance receives the guarded draft and triggering
public chat, and may receive the public show policy; it advises only, never releases a line.
The optional scene scaffolder downloads pinned, SHA-256-checked three.js and three-vrm archives
from registry.npmjs.org. Plugin installation and Hermes dependency preparation can contact Git
and package services.

Listeners. All On Air listeners bind 127.0.0.1, not the LAN:

Local processes can access unauthenticated pages. The Hermes dashboard has its own authentication
and proxies control requests; it is not the same listener as the stage desk API.

Processes and jobs. Approved agent-led stage start runs hermes config path, then
hermes onair preflight, then hermes gateway run as a separate process session with a reduced
environment. It checks process identity and may signal its own process group on stop; status
also probes process existence. Preflight temporarily binds a loopback socket to check the overlay
port. Preview, show and presentation use background threads/event loops; setup and cleanup have
worker/watch threads, and the stage runs chat, speech and timing tasks. The gateway continues
until stopped. Optional development and install-verification tools can run subprocesses, create
throwaway homes, use local listeners and, when allowed, download dependencies; see
compatibility and tools.

Files, secrets and retention. Runtime data is under <HERMES_HOME>/plugin-data/on-air/:
receipts, seed usage, setup plans and job state, preview/show facts and tokens, stage process
records and logs, temporary voice clips and optional OBS startup packets. Receipts can contain
viewer names and line text. Tokens are local secrets; protect this directory and delete retained
data when no longer needed. Setup also creates a new stage home outside that directory, with
config.yaml, a nonsecret sender .env, public SOUL.md, a seed bank and a marker; later
customization updates stage files. The optional OBS startup-packet consumer writes to a new
operator-selected OBS configuration root, not an existing one. Hermes and OBS maintain their own
configuration and data. The plugin reads configured seed-bank files, stage configuration and
persona, installed plugin files and process metadata for readiness and stop verification.
The text-only work view publishes text explicitly supplied by the owner agent; it does not read
files, and its filters are not a guarantee against disclosure. See Work view.

On Air reads ONAIR_OBS_PASSWORD and ONAIR_JEV_API_KEY at call time through Hermes
agent.secret_scope.get_secret; if that API is unavailable, they are treated as empty. Hermes
may use the process environment in single-profile operation, but refuses an unscoped read under
multiplexing. Other ONAIR_* settings and HERMES_HOME can come from settings or environment.
To check the sender allow-list for a marked stage, the dashboard asks Hermes to build the selected
profile's scoped values; Hermes may read that profile's .env and configured secret sources.
The runtime does not parse .env itself. It writes the nonsecret stage sender .env during approved
setup and checks for an installation project .env without reading its contents. The standalone
developer verifier does not read .env files: it checks metadata when refusing an existing synthetic
stage home and refuses a source tree containing one. Metadata is not a content hash; separate tests
check the generated fixture's contents and sentinel isolation. Model credentials belong to Hermes, not On Air's setup plans.
On Air has no telemetry or self-update mechanism.

Limitations (by design)

• The guard is a deterministic backstop, not a prompt-injection boundary. Keep the stage isolated
  and a human operator ready to cut output.
• Requests to translate, define, decode, repeat or say viewer-supplied text are skipped. Quoted
  targets are not echoed. Armed refusals are silent too; bait gets no spoken reaction.
• The decoder covers base64, hex, URL encoding, rot-N, reversal, per-word reversal and atbash.
  Unknown unannounced ciphers, some translation paraphrases and a single joined handle can pass.
• Base64 and lookalike supporter names become “someone”; rot13 or reversed names can show as
  written. An encoded-looking non-word in a host line can be withheld, including innocent text.
• Moderated chat already shown cannot be recalled until it scrolls away. Alerts air immediately
  in approval mode, though the thank-you line still waits for approval.
• The curated English word filter misses unlisted terms and unsupported obfuscation, and may
  block innocent uses. Keep Twitch AutoMod and human moderation enabled.
• The overlay has no built-in avatar, and no camera, guest or host video is provided. An optional
  owner 3D scene can be added separately. Typed private-show input is not Twitch
  intake. Voice needs your own Hermes TTS configuration and a listening test.
• On Wayland the owner confirms the share; OBS cannot attest whether it is a window or a screen.
  Layout changes to a scene already on program are visible immediately.
• macOS and Windows have not been tested in the documented compatibility matrix. See its
  distinctions between native execution, test doubles and defined but unexecuted CI.

Manual setup and reference

• Documentation index: all guides in one place.

• Quickstart: install and rehearse privately.

• Streaming setup: stage, OBS, views and going live.

• Troubleshooting: symptoms and safe checks.

• FAQ: common questions and limits.

• Safety: owner decisions, controls and their limits.

• Views: three boxes and window sharing.

• Host turns: typed lines to the co-host.

• Seed bank: prepare the show rundown.

• Getting started: manual CLI setup, offline rehearsal and settings.

• Agent setup: approvals, preview, private show and real stage.

• Production: briefs, layouts and recovery.

• Presentation: slides, OBS, shared windows and broadcast.

• Desk: operator controls and optional semantic assistance.

• Overlay: browser source, captions and audio.

• Optional 3D scene: owner-built room and bring-your-own VRM.

• Compatibility: tested matrix, install verification and data removal.

• Design specification: contracts and numbered invariants.

Compatibility

Hermes 0.22.7 or newer is required, using Hermes's Python 3.14 runtime. On Air has no
Python dependencies of its own. The documented local matrix includes Linux tests; macOS CI is
defined but not executed, and Windows is not covered. Python 3.11–3.13 are not promised by
Hermes for this runtime. See compatibility for exact test scope.

Development

The dependency-only smoke suite below covers core, guard, word filter and portability tests; it
is not the full suite. In a clean environment it should report passes and skips (including
Hermes-dependent portability checks), with no failures:

uvx --with pytest --with pyyaml --with websockets --with ruamel.yaml --with fastapi --with httpx pytest -q -p no:cacheprovider tests/core tests/guard tests/wordfilter tests/portability

For the full suite, use Hermes's supported Python 3.14 runtime, a matching Hermes checkout, and
pytest plus the dependencies above available to that interpreter. Set HERMES_TEST_PYTHON to
that Python and HERMES_SDK to the checkout; add the test dependencies to its environment or to
PYTHONPATH. From the repository root run:

PYTHONPATH="$HERMES_SDK${PYTHONPATH:+:$PYTHONPATH}" "$HERMES_TEST_PYTHON" -B -m pytest -q -p no:cacheprovider
hermes plugins validate . --install-deps
hermes onair rehearse        # once installed: the gate, guard and stage controller, offline

The full suite should report passes and environment-dependent skips, not failures; a skip is not
proof that its integration ran. Browser and installed-runtime checks may require extra opt-in
fixtures. See docs/REVIEW.md for the review checks.

License

MIT. The word filter includes a subset of LDNOOBW under CC BY 4.0 and entries also present in
better_profanity under MIT; see its attribution. The guard's English
Speller Database word list has its own permissive notice in
WORDLIST-LICENSE.txt.

README from the reviewed commit d40b6ef; it updates when the author re-pins.