Store an API key (read from stdin, not argv)\nvoice-box token --rotate Replace the panel auth token\nvoice-box doctor --selftest Diagnose the install and play a test tone\nvoice-box start|stop|restart Manage the daemon\nvoice-box logs [-n N] Show the daemon log\n```\n\n---\n\n## Configuration\n\nEverything lives in `~/.voice-box/` (mode `0700`):\n\n| File | Contents |\n| --- | --- |\n| `config.json` | Settings and agent profiles. Contains no secrets — safe to share in a bug report. |\n| `secrets.json` | API keys, mode `0600`. |\n| `daemon.json` | Runtime pid, port, and auth token. Removed on clean shutdown. |\n| `token` | Panel auth token, mode `0600`. Persists across restarts. |\n| `history.jsonl` | What was spoken. |\n| `cache/` | Synthesized audio, content-addressed and pruned automatically. |\n\nEnvironment variables always take precedence over stored keys:\n\n```bash\nOPENAI_API_KEY=... ELEVENLABS_API_KEY=...\n```\n\nSet `VOICE_BOX_HOME` to relocate the directory, or `VOICE_BOX_AGENT_NAME` in an MCP\nconfig to pin an agent's name.\n\n> On Windows, file permissions are inherited from your user profile — `chmod` is a no-op\n> there, so the `0600` protection described above does not apply.\n\n---\n\n## Privacy and security\n\n- The HTTP server binds **`127.0.0.1` only**. There is no setting to change that.\n- Requests are authenticated with a 256-bit token stored at `~/.voice-box/token`\n (mode `0600`) and rejected if the `Host` or `Origin` header does not match\n loopback — which blocks DNS-rebinding attacks from a malicious web page. The token\n persists across restarts so an open panel tab keeps working; rotate it any time\n with `voice-box token --rotate`.\n- The panel receives your API key **only as a masked hint** (`sk-…a1b2`). The raw key\n never leaves the daemon.\n- Logs pass through a redaction filter, so a key cannot be written to disk by accident.\n- The only network calls are to the TTS provider you configured.\n\n---\n\n## Troubleshooting\n\n**No sound.** Run `voice-box doctor --selftest`. On Linux, install one of the players\nlisted under Requirements.\n\n**\"No text-to-speech provider is configured.\"** Add a key in Settings, or set\n`OPENAI_API_KEY` before starting the daemon.\n\n**The daemon will not start.** Run `voice-box daemon` in a terminal to see the error\ndirectly, or `voice-box logs`.\n\n**A stale agent is listed.** Use the FORGET button on its strip (shown once it is\noffline).\n\n**Pause doesn't stop mid-word.** That needs mpv (`brew install mpv`), then\n`voice-box restart`. Without it, pause takes effect at the end of the current\nsentence.\n\n**Port 4517 is taken.** Voice Box tries 4517–4527 automatically. Pin one with\n`daemon.port` in `config.json`.\n\n---\n\n## Upgrading from 1.x\n\nVoice Box 2.0 is a clean break.\n\n| 1.x | 2.0 |\n| --- | --- |\n| `args: [\"-y\", \"@anomalypoint/voice-box@latest\"]` | add `\"mcp\"` as a final argument |\n| `env: { OPENAI_API_KEY }` in the MCP config | remove it; set the key in the panel |\n| `text_to_speech` tool | `speak` |\n| `voice` and `model` tool arguments | removed — voice is assigned in the panel |\n| ffmpeg required | no longer used |\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run dev # runs the CLI from source\n```\n\nNo bundler and no CDN: the control panel is plain HTML, CSS, and ES modules, served\nstraight from the package, and works offline.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","readmeFilename":"README.md"}