🎤 ZKA Voice Agent

Full-featured voice AI agent — record your voice, get responses. Has memory, can manage cronjobs, send messages, and more.

🚀 Quick Start

1. Clone & Setup Server

git clone https://github.com/zeroknowledge0x/zka-voice.git
cd zka-voice/server
chmod +x setup.sh && ./setup.sh

2. Edit Config

# API keys (required)
nano .env

# Agent config (optional)
cp hermes_config.json.example hermes_config.json
nano hermes_config.json

3. Start Server

python3 audio-server.py

Open http://localhost:8082 in your browser. Done! ✅

---

🌐 Deploy Web Client (Free)

Host the web UI for free — no server needed for the frontend!

Option A: Vercel (Recommended)

1. Go to vercel.com and sign up with GitHub
2. Click "New Project"
3. Import zeroknowledge0x/zka-voice
4. Set Root Directory to web-client
5. Click Deploy
6. Get your URL (e.g., https://zka-voice.vercel.app)

Option B: Cloudflare Pages

1. Go to pages.cloudflare.com
2. Click "Create a project"
3. Connect GitHub repo zeroknowledge0x/zka-voice
4. Set Build output directory to web-client
5. Click Deploy
6. Get your URL (e.g., https://zka-voice.pages.dev)

Option C: GitHub Pages

1. Go to repo Settings → Pages
2. Source: Deploy from a branch
3. Branch: main, folder: /web-client
4. Click Save
5. Get your URL (e.g., https://zeroknowledge0x.github.io/zka-voice)

---

🤖 Auto-Install (for Hermes Agents)

If you have a Hermes Agent, just say:

"Install ZKA Voice from https://github.com/zeroknowledge0x/zka-voice"

The agent will automatically clone, setup, and run. No manual commands needed!

File: SKILL.md — skill loaded by other Hermes agents.

---

📱 Access from iPhone/Android

# Install cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# Start tunnel
cloudflared tunnel --url http://localhost:8082

Get URL https://xxx.trycloudflare.com — open from phone.

---

🔑 API Keys (All FREE)

Service	Purpose	Sign Up
Groq	STT (Whisper)	console.groq.com
MiMo	LLM	mimo.xiaomi.com
Edge TTS	Text-to-Speech	No sign up needed

Groq is required for STT. MiMo is optional (fallback to Groq if not set).

---

⚙️ Config Examples

See examples/ folder for config samples:

• basic-english.json — Simple, English language
• basic-indonesia.json — Simple, Indonesian language
• full-telegram.json — Full features + Telegram sync
• developer.json — Developer-focused, terminal tools

Usage:

cp examples/basic-english.json server/hermes_config.json
# Edit as needed
nano server/hermes_config.json

---

✨ Features

• 🎙️ Hold-to-Talk — record voice, get audio response
• 🧠 Memory — remembers conversation context
• ⚡ Dual Mode — Chat (natural) & Command (12 tools)
• 🔧 Cronjob Management — manage from voice
• 📱 Telegram Sync — auto-send to topic
• 🔐 Password Protection — token-based auth
• 🌍 Multi-STT — Groq Whisper + MiMo fallback
• 🗣️ Indonesian TTS — Edge TTS ArdiNeural
• 📱 Mobile-Friendly — optimized for iPhone/Android

---

🛠️ Tools (Command Mode)

Tool	Description
cronjob_list	List all cronjobs
cronjob_run	Run a cronjob
cronjob_pause	Pause a cronjob
cronjob_resume	Resume a cronjob
memory_read	Read memory
memory_write	Write to memory
skills_list	List skills
skills_search	Search skills
telegram_send	Send Telegram message
terminal_run	Run command
server_status	Server status
github_repos	List repos

---

🏗️ Architecture

┌──────────────────┐     ┌──────────────────┐     ┌──────────────┐
│   Web Client     │────▶│  HTTP Server     │────▶│   Groq STT   │
│  (Vercel/CF)     │◀────│  (port 8082)     │◀────│  (Whisper)   │
└──────────────────┘     └──────┬───────────┘     └──────────────┘
                                │
                         ┌──────▼───────────┐     ┌──────────────┐
                         │   MiMo LLM       │────▶│  Edge TTS    │
                         │  (or Groq)       │◀────│ (ArdiNeural) │
                         └──────────────────┘     └──────────────┘

Pipeline: Audio → ffmpeg → Groq STT → LLM → Edge TTS → Audio

Latency: ~3-5 seconds total

---

📁 Project Structure

zka-voice/
├── web-client/                 # Static web UI
│   ├── index.html             # Main UI (hold-to-talk, dual mode)
│   └── config.js              # Server URL config
├── server/                     # Python backend
│   ├── audio-server.py        # Main server
│   ├── hermes_context.py      # Context builder (generic)
│   ├── setup.sh               # One-click setup
│   ├── requirements.txt       # Dependencies
│   ├── .env.example           # API key template
│   └── hermes_config.json.example  # Agent config template
├── examples/                   # Config examples
│   ├── basic-english.json
│   ├── basic-indonesia.json
│   ├── full-telegram.json
│   └── developer.json
├── SKILL.md                   # Auto-install skill for Hermes
├── vercel.json                # Vercel deployment config
├── wrangler.toml              # Cloudflare Pages config
├── .gitignore
└── README.md

---

📋 Requirements

• Python 3.10+
• ffmpeg
• Groq API key (free)
• VPS or laptop for server

---

🔒 Security

• Password protection (24h TTL)
• API keys not committed to repo
• Cloudflare Tunnel = automatic HTTPS

---

📝 License

MIT — free to use, modify, and share.

---

🙏 Credits

• Groq — STT Whisper
• Xiaomi MiMo — LLM
• Edge TTS — Text-to-Speech
• Cloudflare — Tunnel & Pages
• Vercel — Web Hosting

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by ZKA Labs