keryx

Start hours of work from a short phone call: you can ask your assistant on the line to research a question, change code, or run an experiment. The work then continues on your machine, even after you hang up. You can check in or add instructions in a later call, and Keryx can call you back or text you the report when it's done. You can call from a phone, or from a watch that can place calls.

[!NOTE] Keryx is pre-1.0. It's self-hosted: it runs on your own machine with your own API keys. While it only answers calls from your own phone number, and asks for your PIN before it does anything on your behalf in case someone spoofs it, please review SECURITY.md before deploying it.

Example requests

"In the imaging project, run a learning-rate sweep on the microscopy images. Call me if you need a decision, and again when training finishes with a quick summary of the results."

"Find the papers my group emailed this week, turn them into a reading-group presentation with polished animations and some discussion questions, and send it to me on Slack."

"Add a voice command that checks whether my home server is up. Build it in the Keryx project and run the tests."

"One more thing: include GPU memory use in that sweep comparison."

Features

Keryx turns the Realtime API into a voice agent that you can use across many calls. This is how it compares with the Realtime API alone and with ChatGPT Voice, as of September 2026:

System overview

Keryx (κῆρυξ) is Ancient Greek for a herald: a messenger who carries word back and forth. That's the job here. Keryx answers the phone, hands your request to a coding agent on your machine, and calls you back with the result. The messenger you talk to on the line is called Lyra by default, and you can rename it with keryx config set ASSISTANT_NAME ….

The conversation runs on the OpenAI Realtime API. Lyra answers small questions itself. Anything larger becomes a task for a coding agent and is handed to Keryx, which keeps running after you hang up.

In this example, one task spans three calls. Keryx calls back once so that Lyra can ask you a question, and again with the training results.

Coding agents: Claude Code or Codex

Tasks run on Claude Code or Codex, signed in with a subscription or an API key. Keryx is most extensively tested with Claude Code on a subscription. Codex is supported, but it may not have every feature. keryx setup asks which agent to use by default. If you enable both, you can say "have Codex do it" on a call. docs/agents.md compares the two.

Quickstart

Requirements

• Linux or macOS, on a machine that stays on, such as a desktop or home server where your projects live. Keryx can't answer calls, keep working, or call you back while it sleeps.
• Python 3.12 and uv.
• An OpenAI API key with Realtime access.
• Claude Code or Codex.
• A Twilio phone number.
• A tunnel that gives Twilio a public address: Cloudflare Tunnel or ngrok.

Install and set up

1. Clone the repository:

   git clone https://github.com/wak31415/keryx.git && cd keryx
   

2. Run the setup wizard. It asks only for what's still missing, and you can run it again at any time:

   uv run keryx setup
   

3. Call your Twilio number.

If a coding agent is setting Keryx up for you, point it at uv run keryx setup --agent-instructions, or give Claude Code the skills/keryx-setup skill. The Setup guide on the wiki covers each step in detail.

Documentation

• Setup guide: the phone, Google, the PIN, where files live, and costs
• Configuration reference: every setting
• Coding agents: signing in, installing only one, and what each can do
• Voice tools: what the voice model can do, and how to add a tool
• Approval bridge: answer Claude Code prompts on your screen by phone
• Security policy and threat model: read it before you put the phone line online
• Wiki: troubleshooting, the command-line reference, and writing your own tools
• Changelog

Getting help

1. Run uv run keryx doctor. It checks the whole setup and says what's missing.
2. Read Troubleshooting on the wiki.
3. If that doesn't solve it, open an issue.

Report a security problem privately, as SECURITY.md describes, never in a public issue.

Roadmap

v0.2.0 plans to add local models for the voice and the agents. v0.3.0 plans to let you talk to the assistant at a Mac, without a phone. A move to OpenAI's GPT-Live is being considered but isn't scheduled. docs/roadmap.md has the checklist for each.

Contributing and license

Bug reports, corrections to the docs, and code are all welcome. See CONTRIBUTING.md. Keryx is licensed under Apache 2.0.