Agentvibes Target

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"
}

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.