Configuring Voice Mode File Uploads in Hermes Agent

Over 40% of community issues on the official Nous Research Hermes Agent repository relate to media pipeline routing and asset delivery rather than simple voice-to-text transcription [Nous Research 2026]. This statistic reflects a common developer bottleneck. While configuring a basic text-to-speech loop or local voice chat is straightforward, setting up the backend to handle media files dynamically within a voice conversation is far more complex. Most developer tutorials explain how to run voice mode for basic CLI chat but skip the plumbing of how generated file assets are returned to messaging channels. To install and test this pipeline, developers can follow the official documentation on the Hermes Agent repository.

Voice mode file uploads refer to Hermes Agent's ability to receive voice messages, transcribe them via Speech-to-Text, and attach output media dynamically back into the communication channel. When a developer commands the agent via voice to generate a chart, extract data from a document, or record an audio response, the agent must output the resulting file path in a way that the platform gateway can capture and upload. Without this dynamic pipeline, the agent is restricted to text responses, which limits its utility in hands-free production environments.

Building a production-ready voice gateway requires coordinating local audio dependencies, defining transcription engines, and structuring the output stream. The agent must process raw audio inputs, run local or cloud models, write output files to predictable locations, and signal to the gateway that the files are ready for upload.

To enable voice capabilities, you must install system-level audio libraries on the host machine where Hermes Agent is running. The framework relies on external libraries to capture microphone input and convert audio formats. Specifically, Hermes voice mode requires ffmpeg and portaudio to function correctly.

PortAudio is the utility that manages real-time microphone input and speaker playback during CLI sessions. Without it, the Python audio recording bindings will fail to initialize. FFmpeg handles the critical task of audio format conversion. For example, when your agent generates a text-to-speech response, the audio must be transcoded into an optimized format like Opus for Discord or Telegram voice messages. If FFmpeg is missing, the agent will fail to transcode the file and will instead output raw audio files that cannot play natively inside chat client bubbles.

To set up these system dependencies on macOS, run the following commands:

brew install portaudio ffmpeg opus espeak-ng

To set up the dependencies on Ubuntu or Debian Linux, run:

sudo apt update && sudo apt install -y portaudio19-dev ffmpeg libopus0 espeak-ng

Once the system dependencies are installed, you must install the specific voice extras for the agent. If you are using Python, you can run:

cd ~/.hermes/hermes-agent && uv pip install -e ".[voice,messaging]"

After installing the packages, you configure your Speech-to-Text (STT) and Text-to-Speech (TTS) engines in the local configuration file located at ~/.hermes/config.yaml. Edge TTS is the default Text-to-Speech provider for the agent, which is free and does not require external API keys.

Below is an example configuration showing how to specify the STT and TTS backends:

voice:
  stt:
    provider: "local"
    model: "faster-whisper"
  tts:
    provider: "edge"
    voice_id: "en-US-AndrewNeural"

Once the voice input is transcribed and processed, the agent generates a text response. If the response requires sending a file, such as a PDF report or a generated audio response, the agent uses a specialized notation to notify the gateway. The featured snippet strategy for this workflow relies on the MEDIA tag notation.

The messaging gateway (such as Telegram or Discord) monitors the agent's text output stream. When the agent wants to send a file, it appends a line in the format MEDIA:/absolute/path/to/file to its response. The gateway intercepts this token, extracts the absolute file path, and handles the platform-specific upload process.

The sequence of this dynamic delivery pipeline is structured as follows:

• The agent runs a tool that creates a file on the local disk, such as /opt/hermes/reports/summary.pdf.
• The agent appends MEDIA:/opt/hermes/reports/summary.pdf to the response stream.
• The gateway processes the text stream, identifies the MEDIA: prefix, and verifies that the file exists.
• The gateway uploads the file as a native attachment using the platform API.
• The gateway removes the MEDIA: line from the message text before showing it to the user.

Below is a Python demonstration showing how the gateway intercepts the stream and processes absolute paths for upload:

import os
import re

def process_agent_response(response_text, gateway_client, chat_id):
    media_pattern = r"^MEDIA:(.+)$"
    lines = response_text.splitlines()
    clean_lines = []
    
    for line in lines:
        match = re.match(media_pattern, line.strip())
        if match:
            file_path = match.group(1)
            if os.path.exists(file_path):
                gateway_client.send_document(chat_id, file_path)
            else:
                gateway_client.send_message(chat_id, f"Error: File not found at {file_path}")
        else:
            clean_lines.append(line)
            
    return chr(10).join(clean_lines)

This dynamic extraction ensures the user receives clean text alongside native attachments. If the gateway fails to run this extraction step, the raw MEDIA: text remains visible in the chat, indicating a breakdown in the delivery pipeline.

Running an autonomous agent in a container or on a cloud VM presents a persistence problem. When the agent generates a file, it must be stored in a reliable location that both the agent and human team members can access. File ephemerality is a major concern when designing these workflows.

Developers typically look at a few common storage options:

Local Ephemeral Disk Using the local disk is fast and requires no extra setup, but the files are lost whenever the container is rebuilt or the VM restarts. Furthermore, other team members cannot view the files without setting up custom web servers or SSH access.

AWS S3 Buckets Cloud object storage is durable, but it requires writing custom integration code and managing complex IAM keys. Non-technical users cannot easily browse the files, check edit history, or edit documents alongside the agent.

Fastio Workspaces To build a shared workspace where agents and humans collaborate, developers can connect their agent to Fastio. Fastio provides persistent, secure storage where every upload is automatically versioned.

By deploying the official Fastio MCP server, your agent can read and write files directly inside a secure cloud directory. Fastio supports MCP-native access via Streamable HTTP at https://mcp.fast.io/mcp or legacy Server-Sent Events at https://mcp.fast.io/sse. API keys allow you to connect your local Hermes instance directly to your workspace. The documentation outlines the action-based toolset on our Fastio MCP server guide, and you can onboard your agent using the fast.io/llms.txt instructions.

Every file stored in a Fastio workspace benefits from automated versioning. If your agent edits a collaborative note or uploads a revised PDF, the prior versions are preserved. If an automated script makes an unwanted change, you can view the diffs and restore the file to a previous state. This ensures that concurrent edits by humans and agents remain fully auditable.

Persist Hermes Agent files across sessions

Set up a shared cloud workspace for your agent's reads and writes with built-in versioning, semantic search, and metadata extraction. Starts with a 14-day free trial.

Start 14-Day Trial

With system dependencies, gateways, and cloud storage configured, you can build end-to-end voice workflows. For example, you can direct your agent to extract structured data from an uploaded PDF invoice using a voice command, and have the agent write the structured output to a spreadsheet.

To process files and extract structured tables, Fastio provides Metadata Views. This structured extraction layer turns documents into a live, queryable database. You describe the columns you want extracted in natural language, and the platform suggests a schema supporting Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time.

Unlike general vector search, Metadata Views act as a structured database over your files. You can learn more about this capability on the Metadata Views product page.

Hermes Agent should talk to Fastio through the official MCP server. Point the agent at Streamable HTTP on https://mcp.fast.io/mcp, or https://mcp.fast.io/mcp/key when the client sends a Bearer token. The named-mode metadata tool is how the agent creates templates, extracts fields from the invoice, and exports the view:

import os
import requests

MCP_URL = "https://mcp.fast.io/mcp/key"
HEADERS = {
    "Authorization": f"Bearer {os.environ['FASTIO_API_KEY']}",
    "Content-Type": "application/json",
}

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "metadata",
    },
}
response = requests.post(MCP_URL, headers=HEADERS, json=payload)

After the extracted table is written to a local file, the agent appends a MEDIA: line so the voice gateway can attach it. Once the file is on disk, the agent appends MEDIA:/tmp/extracted_invoice.csv to the text response. The voice gateway uploads the file, and the source invoice stays in the Fastio workspace.

This entire pipeline is supported under Fastio organization accounts. The Starter plan is $29/mo, the Business plan is $99/mo, and the Growth plan is $299/mo. Every organization starts with a 14-day free trial that requires a credit card to activate. You can manage these settings on our pricing page.

When debugging voice mode and dynamic file delivery, you should first run the diagnostic check built into the agent:

hermes doctor

This utility verifies that your path variables are configured correctly and that the local system can access PortAudio and FFmpeg. If the diagnostic returns errors, you can run the repair flag:

hermes doctor --fix

If the agent transcribes voice input correctly but fails to return audio attachments or files, check for the following common issues:

Missing FFmpeg in Path If ffmpeg is not in the system path of the shell session running the gateway, the agent cannot transcode files. On macOS, this often happens because background services do not inherit the shell PATH. Verify that your launch configurations include the full path to /opt/homebrew/bin or /usr/bin.

Gateway Bypassing Extraction If the MEDIA: string is printed as plain text in Discord or Telegram, the gateway has bypassed the extraction step. This happens when the response is routed through queued follow-up queues or when the tag is formatted inside a code block. Ensure the agent outputs MEDIA: on a new line outside of code blocks.

Attachment Size Limits Messaging platforms enforce strict upload limits. Discord limits standard attachments to 25MB, and Telegram limits files to 2GB. For large files like HLS video assets or datasets, you should avoid native gateway uploads. Instead, configure your agent to write the files to a Fastio shared folder. Fastio Receive and Exchange shares support large files, and recipients can stream high-definition media directly from their web browser.