Getting Started

Keryx is the fullstack TypeScript framework for MCP and APIs. It's the spiritual successor to ActionHero, rebuilt from scratch on Bun with Zod for validation, Drizzle for the ORM, and a Vite + React frontend. The core ideas are the same — transport-agnostic actions, built-in background tasks, strong typing between frontend and backend — but the tooling and scope are different.

Write your controller logic once, and it works as an HTTP endpoint, WebSocket handler, CLI command, background task, and MCP tool — all at the same time. Enable MCP_SERVER_ENABLED=true and AI agents can discover and call those same actions as MCP tools.

The name Keryx (κῆρυξ) comes from ancient Greek, meaning "herald" or "messenger" — the person who carried proclamations between gods and mortals. It fits: your actions are the message, and Keryx delivers them across every transport.

Prerequisites

You'll need these running locally:

• Bun (latest)
• PostgreSQL
• Redis

Installation (macOS)

# install bun
curl -fsSL https://bun.sh/install | bash

# install postgres and redis
brew install postgresql redis
brew services start postgresql
brew services start redis

# create a database
createdb bun

Create a New Project

bunx keryx new my-app
cd my-app
cp .env.example .env
bun install

The keryx new command will prompt you for a project name and optional features (database setup, example action). You can also skip prompts with --no-interactive:

bunx keryx new my-app --no-interactive

Run the Dev Server

bun dev

That's it. The backend will start with hot reload — edit a file, save it, and see the change immediately.

Project Structure

A new Keryx project looks like this:

my-app/
├── actions/        # Transport-agnostic controllers
├── channels/       # WebSocket PubSub channels
├── drizzle/        # Generated migration SQL
├── initializers/   # Lifecycle components (DB, Redis, etc.)
├── middleware/     # Action and channel middleware
├── schema/         # Drizzle ORM table definitions
├── index.ts        # Sets api.rootDir, re-exports framework types
├── keryx.ts        # CLI entry point
├── .env.example    # Environment variable template
└── package.json

Actions, initializers, and channels are auto-discovered from their directories — just drop in a .ts file and the framework picks it up.

Generate Components

Use the CLI generator to scaffold new components with boilerplate:

bunx keryx generate action user:create
bunx keryx g initializer cache        # "g" is a shorthand alias

This creates the component file and a matching test file. See the CLI guide for all generator types and options.

What's Next

• Actions — the core concept. Everything is an action.
• Initializers — how the server boots up and connects to services
• Tasks — background jobs and the fan-out pattern
• Configuration — environment-based config with per-env overrides
• Building for AI Agents — expose your actions as MCP tools for Claude, Cursor, and other AI clients