MIKODES VOX
an assistant that calls you.
Everything you need to install, configure, brand and run your own AI voice assistant, alone or as a subscription service. Read it top to bottom the first time. After that, press / and search.
01What you bought
VOX is a personal AI assistant that speaks first. It learns its user through 12 questions, runs errands for them (research, mail watching, reminders, desktop clean-up) and then calls their mobile to tell them the result. The conversation is a real two-way phone call: you can interrupt it and it stops talking.
You get the full source code. You, the operator, run it on your own server with your own provider accounts and under your own brand. MIKODES does not operate anything: there is no licence server, no phone-home and no telemetry.
| Mode | Command | Who it is for |
|---|---|---|
| Single-user | python -m voice up | One person, one install. A local console on 127.0.0.1:8766, the job worker and the media server for calls. |
| SaaS | python -m voice saas | You sell subscriptions. A public site with sign-up, one private console per customer at /app/, an operator panel at /op/, Stripe billing, plans and quotas. |
Every feature described here is built and covered by offline automated tests (fake Twilio, Telnyx, Stripe, Google and model endpoints). Not one real phone call, SMS, Stripe payment, Google sign-in or live research request has been made from this code base. Your first call is the first call. Make it to your own phone and listen before you put users on it.
The package contains no API key, token, password or credential of any kind. Supplying every key is an installation step (Configuration).
02What VOX does
- Profile. 12 onboarding questions build a 500-point profile in 16 categories. Every fact records its source (asked, corrected, inferred). Inferred facts are marked and can be deleted one by one or all at once.
- Two-way phone calls with barge-in: Twilio (or Telnyx) → ElevenLabs speech-to-text → Anthropic Claude → ElevenLabs text-to-speech, built on pipecat 1.11.0. Optional local speech with your own Piper and whisper.cpp servers.
- Jobs that end in a call: research (Claude with web search, only real sources), agent tasks (a planner with read-only helpers, hard cost limits), desktop clean-up with preview, confirmation and undo, reminders, a morning briefing, wake-up rituals and a mail watcher that calls when something important arrives (Gmail, read-only).
- Google Calendar (read; new events only as proposals you confirm) and MCP servers (registered with a mandatory licence field; write tools always wait for confirmation).
- Messages to yourself by SMS, WhatsApp (Twilio only), Telegram or e-mail, a fixed list of text commands, and inbound calls protected by a PIN.
- PC actions (single-user mode only): 17 file actions with plan → confirm → undo, and optional mouse and keyboard control that is off by default.
- SaaS mode: accounts, plans, quotas, a usage ledger, credit packs, Stripe Checkout and Customer Portal, branding, margin analytics.
Feature by feature, with what is verified: docs/10-FEATURES.md in the package.
03Pick your path
04What is in the package
| Folder or file | What it is |
|---|---|
app/voice/ | The Python engine: calls, worker, console, SaaS mode (app/voice/saas/), tests (app/voice/tests/). |
app/src/ | The Node onboarding and briefing (node src/run.js). |
app/voice/VERSION | The version number (2.0.0). |
Dockerfile, docker-compose.yml | One image with Python 3.11 and Node 20, no key inside. |
deploy/ | install.sh, vox.env.example, Caddyfile.example, nginx-vox.conf.example, systemd/ units. |
scripts/make_demo.py | Builds a labelled DEMO data directory for trying the product. |
docs/ | Design documents and the longer install guide (docs/08-INSTALLATION.md). |
documentation/ | An offline HTML copy of the guide (documentation/index.html). |
CHANGELOG.md, SOURCES.md, LICENSE | Changes, third-party sources and licences, your licence. |
A Linux server (or macOS for single-user), a public host name with HTTPS, and your own accounts with Anthropic, ElevenLabs (or your own Piper/whisper.cpp servers), Twilio or Telnyx, and optionally Stripe, an SMTP server, a Telegram bot and a Google Cloud OAuth client. None of these are part of the purchase, and you pay their usage fees.
05Try it before you install
A public demo runs SaaS mode on a labelled demo data directory: vox-demo.mikodes.com. The login page offers one-click demo roles for a customer console and the operator panel. The demo is read-only for every visitor and places no calls.
The demo is a build started with VOX_PUBLIC_DEMO=1 on a directory made by scripts/make_demo.py. Your own install has no demo accounts.
06How to read these docs
- Dark boxes are commands. Press Copy in the corner and paste them into a terminal.
- Grey text after
#is an explanation. The Copy button leaves it out. - Text in angle brackets, like
<your-host>, is a placeholder. Replace it, brackets included. - All
python -m voice …commands run from theapp/folder with the virtual environment active (bare metal), or inside the container (Docker). - Required marks steps you cannot skip. Unverified marks things that have not run against a real service or server.