Home

Keryx is a personal voice agent you can reach by phone. Keryx (κῆρυξ) is Ancient Greek for a herald: a messenger who carries word back and forth. The messenger you talk to on the line is called Lyra by default, and you can rename it with keryx config set ASSISTANT_NAME ….

Lyra answers simple questions during the call and hands larger tasks to Claude Code or Codex on your machine. If a task finishes after you hang up, Keryx can call you back with the result. Talking to Keryx locally on a Mac, with no phone, is in development on the feat/local-wakeword branch and isn't part of main.

Keryx is a single-owner service that you run on your own machine, with your own API keys. It isn't published to PyPI or any other package index. Read Assumptions and Deployments before you deploy it anywhere shared.

This wiki covers setup, running Keryx, security, and troubleshooting. For a project overview and a quick start, see the README. The repository also has the reference documentation:

• SECURITY.md — the threat model.
• docs/configuration.md — every setting.
• docs/agents.md — the coding agents, and what each can do.
• docs/tools.md — the tools the voice model can call, and how to add one.

Setting up

Run uv run keryx setup. It asks only for what's still missing, and saves as it goes. If a coding agent is setting Keryx up for you, start it from uv run keryx setup --agent-instructions. Settings live in ~/.config/keryx/config.toml and secrets.toml. uv run keryx doctor says what's left.

• Setup — the phone, the PIN, Google, the plugins, and what it costs.

Running it

• Running as a Service — the systemd and launchd units, where they log, and which unit a restart talks to.
• Restarting Keryx — why Keryx phones you back after a restart, how it knows the change loaded, and the watchdog for a restart that never comes back.
• Command Line Reference — every keryx command and what it's for.
• Google Workspace MCP — optional Google access: read-only email answers on a call, and Gmail and Calendar for Codex tasks.
• Troubleshooting — start with keryx doctor, then the logs, then the common cases.

Security and data

• Security Model — tasks run as you, what the tunnel exposes, the PIN, and the three levels of trust a call can have.
• Data and Retention — what's written to disk, what leaves the machine, and how to delete it.
• Assumptions and Deployments — the single-owner model, and other assumptions built into Keryx.

Tools and advanced features

• Custom Tools — give Keryx a new ability on the phone, by asking for one out loud or by writing one yourself.
• Sharing Custom Tools — a suggested way to publish your tools and install someone else's, and why you should read them first.
• The Approval Bridge — answer Claude Code's prompts by phone when you're away from the keyboard.

Corrections

Corrections are welcome, especially for setup instructions that are wrong. Please open an issue in the repository. If you want to contribute, see CONTRIBUTING.md. To report a security issue, don't open a public issue: use the repository's Security tab and select Report a vulnerability.