agentvibes-target

name	agentvibes-target
description	Send TTS text from Hermes to a Windows laptop or Android device via AgentVibes queue-based player over SSH
category	tts
required_environment_variables	["AGENTVIBES_SSH_KEY","AGENTVIBES_RECEIVER_HOST","AGENTVIBES_RECEIVER_PORT","AGENTVIBES_RECEIVER_USER","AGENTVIBES_ANDROID_HOST","AGENTVIBES_ANDROID_PORT","AGENTVIBES_ANDROID_USER"]

AgentVibes TTS — Send Text to a Remote Device

Architecture

Hermes (VPS/Docker) --[SSH, base64]--> Windows receiver: $AGENTVIBES_RECEIVER_HOST:$AGENTVIBES_RECEIVER_PORT
                                  OR
                                       Android receiver: $AGENTVIBES_ANDROID_HOST:$AGENTVIBES_ANDROID_PORT

Windows: Piper TTS --> speakers
Android: Piper TTS --> speakers

AgentVibes uses a queue-based player: SSH call enqueues a base64-encoded TTS payload and returns immediately; a background worker handles synthesis and playback sequentially.

Two targets are supported:

• Windows (primary) — user agentvibes-receiver, queue-based playback
• Android — via Termux SSH receiver

---

How It Works

The receiver at $AGENTVIBES_RECEIVER_HOST:$AGENTVIBES_RECEIVER_PORT is an SSH server that accepts only base64-encoded JSON payloads — it does NOT execute shell commands and does NOT read from stdin/pty. You pass the base64 string as a command-line argument (not piped or sent via TTY), and it queues the text for TTS playback.

Critical: Do NOT pipe or TTY-send the payload — the receiver ignores stdin. The base64 string must appear as a plain argument after the user@host.

Payload format

The payload is a base64-encoded JSON object. All fields except text are optional — omit or leave empty to use the receiver's current defaults.

{
  "text":     "Words to speak aloud",
  "voice":    "en_US-libritts-high::Leo-8",
  "music":    "bachata",
  "volume":   "0.30",
  "effects":  "medium",
  "pretext":  "Hermes here, ",
  "speed":    "",
  "provider": "piper",
  "project":  "hermes"
}

Field	What it controls	Examples
text	Text to speak	Any string
voice	Voice model and speaker	en_US-libritts-high::Leo-8, en_US-jenny-medium
music	Background music track	bachata, chillwave, dreamy-house, "" = use default
volume	Background music volume (0.0–1.0)	"0.25", "0.40"
effects	Reverb preset (Windows) or Sox string (Linux)	"off", "light", "medium", "heavy", "cathedral"
pretext	Spoken prefix prepended to text	"Hermes here, ", "" = no prefix
speed	Speech rate multiplier	"1.2" = faster, "" = default
provider	TTS engine	"piper"
project	Tag shown in receiver log	"hermes"

To change voice: set voice to any voiceId or voiceId::SpeakerName string. Ask the user which voice they want, or use list_voices if the AgentVibes MCP server is available.

To change music: set music to a track keyword (bachata, chillwave, dreamy-house) or "" to inherit the receiver default.

To remove reverb: set effects to "off".

To add reverb: set effects to "light", "medium", "heavy", or "cathedral".

Step 1: Build and encode the payload

PAYLOAD=$(echo -n '{"text":"Your message here","voice":"","music":"","effects":"","pretext":"Hermes here, ","volume":"","speed":"","provider":"piper","project":"hermes"}' | base64 -w 0)

Step 2: SSH the base64 payload to the receiver

ssh -i "$AGENTVIBES_SSH_KEY" -o ConnectTimeout=10 -o StrictHostKeyChecking=no \
  -p "$AGENTVIBES_RECEIVER_PORT" "$AGENTVIBES_RECEIVER_USER@$AGENTVIBES_RECEIVER_HOST" "$PAYLOAD"

Step 3: Response

Returns Queued for playback: <id> on success.

---

Prerequisites

1. OpenSSH client installed on the Hermes server:

   apt-get install -y openssh-client
   

2. Ed25519 SSH key for the agentvibes-receiver user:

   • Private key at an absolute path (no tilde — subprocess won't expand it)
   • Public key must be registered on the receiver machine

3. Docker networking: If running Hermes in Docker with Tailscale, SSH to Tailscale peers works from inside the container — Tailscale proxies the traffic. Do NOT assume --network=host is needed unless SSH times out.

4. Environment variables must be set in ~/.bashrc (not in .env — that file is not read by the gateway shell):

   export AGENTVIBES_SSH_KEY=/absolute/path/to/id_ed25519
   export AGENTVIBES_RECEIVER_HOST=<your-receiver-tailscale-ip>
   export AGENTVIBES_RECEIVER_PORT=<your-receiver-port>
   export AGENTVIBES_RECEIVER_USER=agentvibes-receiver
   export AGENTVIBES_ANDROID_HOST=<your-android-tailscale-ip>
   export AGENTVIBES_ANDROID_PORT=<your-android-port>
   export AGENTVIBES_ANDROID_USER=<your-android-user>
   

Common Mistakes

Using port 22 — Wrong. The AgentVibes receiver listens on the port configured during npx agentvibes install, NOT 22. Check your receiver setup for the correct port.

Sending plain text or piping — The receiver does NOT read from stdin/pty. It only accepts a base64-encoded string as a command-line argument. If you get "Payload must be base64-encoded", you either sent plain text or tried to pipe/echo into SSH. Correct: ssh ... 'BASE64STRING' with the base64 as an argument.

Using hostname instead of IP — Hostnames may NOT resolve from inside a Docker container (Docker network namespace isolation). Use the direct IP (e.g., Tailscale IP) rather than a hostname alias.

No SSH key mounted — If the container has no SSH key, generate one:

ssh-keygen -t ed25519 -f /absolute/path/to/id_ed25519 -N ""

Then register the public key on the receiver machine's agentvibes-receiver user.

Important Rules

• Always base64-encode the message before sending via SSH — the receiver rejects plain text.
• Keep messages short (~150 chars) — the queue worker plays sequentially, so long messages block subsequent ones.
• Do NOT parallelize SSH calls — wait for each call to return before sending the next.
• The SSH call returns immediately after enqueueing — do NOT wait for audio to finish.
• Messages are queued with a unique ID (e.g., ff81350a) — this is just a queue reference.

---

Switching Target: Windows vs Android

The user can switch between two AgentVibes targets:

1. Windows (default) — $AGENTVIBES_RECEIVER_HOST:$AGENTVIBES_RECEIVER_PORT, Piper TTS, queue-based playback.
2. Android — $AGENTVIBES_ANDROID_HOST:$AGENTVIBES_ANDROID_PORT, user $AGENTVIBES_ANDROID_USER, Piper TTS via Termux.

SSH commands by target

Windows:

ssh -i "$AGENTVIBES_SSH_KEY" -o ConnectTimeout=10 -o StrictHostKeyChecking=no \
  -p "$AGENTVIBES_RECEIVER_PORT" "$AGENTVIBES_RECEIVER_USER@$AGENTVIBES_RECEIVER_HOST" '<base64>'

Android:

ssh -i "$AGENTVIBES_SSH_KEY" -o ConnectTimeout=10 -o StrictHostKeyChecking=no \
  -p "$AGENTVIBES_ANDROID_PORT" "$AGENTVIBES_ANDROID_USER@$AGENTVIBES_ANDROID_HOST" '<base64>'

---

Troubleshooting

"Payload must be base64-encoded" → The receiver requires base64 passed as a command-line argument, not piped via stdin. Correct: ssh ... 'BASE64STRING'. Wrong: echo BASE64 | ssh ... or ssh ... < file.

"Permission denied (publickey)" on Windows receiver → The SSH public key is not registered on the agentvibes-receiver user. Re-run the receiver setup on the Windows machine.

"Permission denied (publickey)" on Android → The same key must be installed on the Android device. Get the public key:

cat /absolute/path/to/id_ed25519.pub

Register it on the Android device and retry.

SSH times out → Docker network namespace issue — Tailscale may not be running inside the container. Try restarting the container with --network=host, or verify Tailscale is active inside the container.

Hook loaded but not working → Gateway must be restarted to pick up new hooks — the hook system is discovered at startup only. → Verify hook is loaded: check gateway logs for discover_and_load() output and confirm hooks/agentvibes-tts/ exists in your Hermes home directory.

---

npx agentvibes

npx agentvibes is a TUI console for interactive setup on the target machine — it does NOT provide a headless API for programmatic sending. Use the Python hook (handler.py) for automated sending from Hermes.

No separate AgentVibes API key is needed. The SSH key is the only credential required.

---

Auto-Speak: Hook on Every Response

See the companion skill hermes-agentvibes-hook for a complete hook that auto-speaks every Hermes response. It fires on agent:end events and handles all encoding, rate-limiting, and error logging.

Useful CLI TTS distinction:

auto_tts: true in Hermes config does NOT make Hermes speak in CLI mode — it only pre-enables TTS once you enter voice recording mode (/voice on). For CLI text-to-speech without voice recording:

• Run /voice tts to toggle TTS on/off
• Run /voice on to enter full voice recording mode (TTS auto-enabled)

auto_tts is NOT a global "always speak" flag.

---

What NOT to do

• Do NOT send plain text to the receiver — always base64-encode
• Do NOT wait for audio playback to finish — the SSH call enqueues and returns immediately
• Do NOT put env vars in .env files that the gateway shell doesn't read — use ~/.bashrc