Setup

Prerequisites

• Linux or macOS.
• A machine that stays on, such as a desktop or a home server where your projects live. Keryx answers your calls, keeps working after you hang up, and calls you back. None of that happens while the machine sleeps.
• Python 3.12 and uv.
• An OpenAI API key with Realtime access.
• Claude Code or Codex, signed in with a subscription or an API key. Keryx is most extensively tested with Claude Code on a subscription. Other agents are supported in principle, but may not have full feature parity. See the comparison of Claude Code and Codex.
• For the phone: a Twilio number, and a tunnel through Cloudflare Tunnel or ngrok.

Install

1. Clone the repository:

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

2. Run the setup wizard:

   uv run keryx setup

   The first uv run installs Keryx with both coding agents. If you want only one, see installing a single agent.

3. If you didn't install the background service during setup, start Keryx in a terminal with scripts/dev.sh.

4. Call your Twilio number.

What keryx setup asks

keryx setup saves each answer as you go and skips anything that's already configured. It covers:

• your OpenAI key, which it verifies before saving;
• the coding agent that handles tasks, and its sign-in, unless that agent is already signed in;
• your name, your phone numbers, and your PIN;
• optional sections: Twilio, Google, the plugins (Slack, email answers, billing, and cluster stats), an initial memory, project summaries, and the background service.

It opens on an overview of every section, each marked done, missing, or failed. From there you can set up what's left, walk any one section, or review everything. It asks one question per screen:

• Esc goes back to the previous question.
• Tab skips ahead to the first question you haven't answered.
• A secret you already gave shows only its last four characters. Press Enter to keep it.

You can run it again at any time to complete missing sections. To review everything, use --all. uv run keryx doctor reports what remains.

Letting a coding agent help

To have a coding agent help with setup, give it the output of uv run keryx setup --agent-instructions. The agent can run the keryx config, keryx auth, keryx plugins, and keryx memory commands. It then sends you to keryx setup for the steps that need your input.

If you use Claude Code, you can instead copy skills/keryx-setup into ~/.claude/skills/ and let the skill drive the same path. If CLAUDE_CONFIG_DIR is set, copy it into $CLAUDE_CONFIG_DIR/skills/ instead.

Phone

The phone section verifies your Twilio credentials and lists your numbers. It then guides you through the tunnel setup: Cloudflare Tunnel on Linux, or ngrok on macOS. Before it updates the number's webhooks, it shows you the voice and status URLs and asks you to confirm. The Twilio guide has the details.

There are two ways to run Keryx:

• In a terminal: scripts/dev.sh starts the server and a Cloudflare tunnel.
• As a background service: scripts/install-systemd.sh (Linux) or scripts/install-launchd.sh (macOS) installs the server and the tunnel. The setup wizard can do this for you. See Running as a Service.

Texting is off by default, because many Twilio accounts can't send SMS in every region. If your account can send SMS to your number, turn it on with SMS_ENABLED.

The PIN

If you don't set a PIN during setup, the first caller can create one by entering it twice. Keryx stores it in ~/.config/keryx/pin, and the running service can't change it. See setting the first PIN on the first call in SECURITY.md. Only keryx setup, at the keyboard, can replace an existing PIN.

Google

Google integration is optional. To use it, first create a Google Cloud client with the Google setup guide. There are two separate sign-ins:

• A read-only Gmail sign-in lets Keryx answer email questions during a call. This is the check_email plugin, which you set up in the Plugins section.
• A sign-in for the agents, in the Google section, lets them send email and manage your calendar. Codex needs it for any Gmail or Calendar access.

See Google Workspace MCP.

Plugins

Plugins are the voice tools that only some people want. None is offered until you turn it on:

Plugin	What it does	What it needs
send_to_slack	"Send me that on Slack" posts to your DM. PIN-lockout alerts go there too.	SLACK_BOT_TOKEN and a DM channel ID, or a Slack MCP server that has both
check_email	Answers questions about your email on the call, in about five seconds.	The read-only Gmail sign-in, and the Claude extra
check_billing	Says what the month has cost, from the provider's billing API.	OPENAI_ADMIN_KEY or ANTHROPIC_ADMIN_KEY
cluster_stats	Says what's free on your Slurm clusters, and whether your jobs are running.	An ssh ControlMaster to each host in ~/.ssh/config

The first time through, the Plugins section ticks Slack and email for you. It asks each ticked plugin only for the settings that matter. If you untick a plugin that's on, it asks first and then turns it off.

Each plugin is two files in ~/.local/share/keryx/tools/: a one-line .py, and a commented .toml of its settings that you can edit by hand. Secrets stay in secrets.toml. Changes take effect from the next call, with no restart.

From the command line, keryx plugins install NAME turns a plugin on, keryx plugins remove NAME turns it off, and keryx plugins shows which are on. See Command Line Reference.

You can also give Keryx a tool of your own by asking for one on a call. See Custom Tools.

Settings

uv run keryx config list shows every setting and where its value came from. keryx config set KEY VALUE changes a setting. For a secret, use --stdin, so that it doesn't appear in your shell history. The settings reference describes every key.

Two settings are worth a look if you don't speak English on calls, or if you prefer a 12-hour clock:

• TRANSCRIPTION_LANGUAGE is the language of the call log's transcription, which recall and the memory read. Set it to an ISO-639-1 code such as de. If it's blank, the transcriber guesses.
• CLOCK_FORMAT is 24h or 12h. It sets how Keryx writes the time, and usually how it says it.

During an authorized call, Keryx can change a limited set of its own settings, such as its voice, its turn-taking, and the model that does the work. Credentials, caller access, the PIN, and other security-sensitive settings are protected. To control which other settings Keryx may change, use keryx config lock KEY and keryx config unlock KEY.

Where Keryx keeps its files

Keryx keeps its settings, secrets, and PIN in ~/.config/keryx, and its data in ~/.local/share/keryx. Keep ~/.config/keryx out of any dotfiles repository. keryx config path prints every directory, and Data and Retention describes what's in each one.

Costs

Voice calls incur OpenAI API charges. By default, coding-agent tasks count against your Claude or ChatGPT subscription limits. If you set ANTHROPIC_API_KEY or CODEX_API_KEY, they're billed per token instead.

SUBAGENT_MAX_BUDGET_USD caps what one Claude task may spend, as a guard against a runaway task. It's 10 by default. On a subscription, it's the SDK's estimate of what the task would have cost, not an actual charge.

Related

• Command Line Reference — every keryx command, including the config, auth, and memory seed commands a coding agent uses to set Keryx up.
• Google Workspace MCP — the Google sign-ins in depth.
• Security Model — the PIN, the trust levels, and what the tunnel exposes.
• Data and Retention — what's in each directory, and how to delete it.
• Troubleshooting — when keryx doctor isn't enough.