Skip to content

Get started

Keryx runs on a machine that stays on, such as a desktop or a home server where your projects live. It can't answer calls, keep working, or call you back while that machine sleeps.

You'll need

  • A Linux or macOS machine that stays on
  • An OpenAI API key for voice
  • A Claude or ChatGPT plan, or an API key, for the agent (Claude Code or Codex)
  • A Twilio phone number
  • A tunnel so Twilio can reach your machine: Cloudflare Tunnel on Linux, ngrok on macOS

Install

curl -fsSL https://keryxvoice.ai/install.sh | sh

This installs the keryx-voice package from PyPI into an environment of its own, then opens the setup wizard. The wizard asks only for what's still missing, saves as it goes, and ends by starting the background service. You can run keryx setup again at any time.

Then call your Twilio number. The first call is a short introduction.

If something isn't working, keryx doctor checks the whole setup and says what's missing or broken.

Setting it up with a coding agent

Point the agent at keryx setup --agent-instructions, which prints the command-line path through setup. In a clone, you can give Claude Code the skills/keryx-setup skill instead.

Update

Run keryx upgrade, or ask for an upgrade on a call. Either way Keryx installs the newest release, checks that it starts, and restarts onto it. On a call it waits until you hang up, then calls back from the new version.

Set up from a clone

Installed from a clone, the service runs your checkout. A call can change Keryx's own code, restart it with the changes, and call you back to report whether it started. The agent also reads the code before filing a bug report. This needs uv:

git clone https://github.com/wak31415/keryx.git && cd keryx
uv sync
uv run keryx setup

To update a clone, pull and run uv run keryx restart.

The setup guide on the wiki covers each step in detail: the phone, Google, the PIN, where files live, and what it costs.