# Carbon Voice + Hermes

## Overview

Carbon Voice is the [best interface](../concepts/why-carbonvoice.md) for talking to AI agents on the go.

[Hermes](https://hermes.ai) is an AI agent framework that lets you build and deploy intelligent agents with ease.

Connect Carbon Voice and Hermes so you can **talk** to your Hermes agents like you would a chief of staff or other team member.

## Features of this Integration

- **Talk to it with swipe of a button** — Record voice messages to trigger Hermes agents instantly while on-the-go with the mobile app
- **Talk to it with a desktop shortcut** — Start talking to your agent with a single keyboard shortcut
- **Send even when agent is offline and recovers** — Your messages are queued and delivered when Hermes comes back online
- **Plugin system** — Extend Hermes with the Carbon Voice plugin for seamless integration

---

# What You'll Need

* Create a Carbon Voice "AI Agent" account with API Access
* Hermes installed on your machine
* About 5 minutes

# How it works under the hood

![Carbon Voice agent message flow](../../config/images/cv_agent_message_flow_v2.svg)

The purple boxes are your agent. Carbon Voice handles the rest.

---

# **Step 1** **Install the Carbon Voice Plugin**

Hermes uses a plugin system to extend its capabilities. Install the Carbon Voice plugin to enable voice messaging integration.

```bash
hermes plugins install PhononX/hermes-plugin-carbonvoice --enable
```

---

# **Step 2** **Configure the Plugin with your PAT**

When prompted, enter your Carbon Voice Personal Access Token (PAT). You can get this from the developer portal:

1. Go to [https://developer.carbonvoice.app](https://developer.carbonvoice.app)
2. Click "Agents" on the left side
3. Select your agent or create a new one
4. Scroll down to the "Personal access tokens" section
5. Click "Create token" and save it — **this cannot be retrieved again**

Paste your PAT when prompted by the Hermes plugin.

---

# **Step 3** **Start the Hermes Gateway**

After configuring the plugin, start the Hermes gateway to begin receiving and processing Carbon Voice messages.

```bash
hermes gateway run
```

---

# **Step 4** **Test the Integration**

1. Open the Carbon Voice app on your phone
2. Send a message to your Hermes agent
3. You should receive a response from Hermes

Try a simple test like:
- "What's the status of my current tasks?"
- "Check my system status"
- "What's the latest news?" (if you have news tools configured)

---

# Troubleshooting

| Problem | Solution |
| ----- | ----- |
| Plugin install fails | Make sure you have Hermes installed and have internet connectivity |
| Plugin prompts for PAT again | Verify your PAT is correct and hasn't expired |
| No response from Hermes | Check that the gateway is running with the correct status |
| Gateway won't start | Check Hermes logs for errors, ensure no port conflicts |
| Messages not received | Verify the PAT has the correct permissions for your agent |

---

# Security Notes

- Your Carbon Voice PAT is stored in Hermes's configuration. Keep your machine secure.
- Never commit your PAT to version control
- If you suspect your PAT has been compromised, revoke it immediately from the developer portal and create a new one
- Hermes runs locally on your machine, giving it access to your files, tools, and workflows. Only install Hermes from trusted sources

---

# Advanced Configuration

### **Custom Plugin Settings**

You can customize the Carbon Voice plugin behavior by modifying the Hermes configuration files. Check the Hermes documentation for plugin-specific settings.

### **Multiple Agents**

If you have multiple Carbon Voice agents, you can configure multiple instances of the plugin with different PATs.

### **Logging and Debugging**

To enable detailed logging for the Carbon Voice integration, check the Hermes logs:

```bash
hermes logs
```

This can help diagnose connection issues or message delivery problems.