kentcdodds/kody: a portable MCP home for your AI assistant

What kody actually solves, and who it is built for

Most people running an AI agent across more than one host end up with the same problem: the agent's memory, API keys, saved snippets and scheduled tasks live inside whichever host they started with. Move to a different MCP host and you rebuild all of it. Kody's pitch is that those things should live in one place the agent owns, and that place should be reachable from any MCP host.

The README describes kody as "your assistant's home, the memory, keys, code, and automations your AI agent keeps, portable across every MCP host." The scope section is equally direct about what it is not: a "Fair Source personal assistant platform, not a general-purpose agent harness." That distinction matters. If you want a framework for wiring arbitrary tools into arbitrary models, kody is the wrong shape. If you want a hosted home for one assistant's persistent state, it is the right one.

It is explicitly multi-user. According to the README, each signed-in user gets "a fully isolated assistant (packages, jobs, secrets, memories, and related state)," and no account is privileged at runtime. That makes it a fit for a small team or a family instance rather than a single-user toy, and it means the isolation model is part of the product, not an afterthought bolted on later.

The worker fleet: how a request moves through kody

Kody is not one Worker. The README's architecture diagram shows four, split by responsibility. kody.codes resolves to kody-production, which is the origin: Remix pages, the /mcp HTTP endpoint, OAuth, email and queues. It fans out to kody-platform, which hosts Durable Objects for MCP state, a mailbox, a meter and repo sessions. kody-runtime runs package apps, an invoke API and something called StorageRunner. kody-jobs handles cron and a JobManager that calls back through a JobsHost.

There is a second zone. kody.run routes to kody-runtime for package-app zone routes, which is how user packages get their own address space without going through the origin.

Request handling inside the origin is ordered, and the order is documented in the README: OAuth requests are handled first, then MCP requests, then static assets. Anything that is not an asset falls through to the server handler and router. Client assets are bundled into packages/worker/public/ and served through an ASSETS binding. If you are debugging why a request never reaches your handler, that sequence is the first thing to check.

The repo is an Nx monorepo. Shared modules live in packages/shared under the @kody-internal/shared import name, the origin app is packages/worker, and the sibling workers are packages/platform-worker, packages/runtime-worker and packages/jobs-worker. Mock Workers sit under packages/mock-servers/*. Storage is Cloudflare D1 for the database, Cloudflare KV for sessions and OAuth, and Durable Objects on kody-platform for MCP state.

Installing kody and running the dev server for the first time

The README's Quick Start is two commands. Run them from the repository root:

npm install
npm run dev

The dev server listens on localhost:3742 by default. The README notes that the CLI picks the next free port if 3742 is taken and prints the resolved URL, so read the terminal output rather than assuming the port. Wrangler handles the local Cloudflare Workers runtime and the D1 database automatically, so there is no separate database step for local development.

If you want to see how the dev script is actually wired, the package.json dev script is `node --env-file=packages/worker/.env cli.ts`. That means a packages/worker/.env file is expected. The repository also ships `npm run dev:ensure` as `node --env-file-if-exists=packages/worker/.env tools/ensure-dev.ts`, which is the softer variant that tolerates a missing env file.

For a first real use, the README points at docs/use/index.md for using kody over MCP, and at docs/contributing/getting-started.md for the full setup paths, environment variables and deploy. Contributors and agents are told to start with AGENTS.md. If you only want to read about intent before installing anything, docs/contributing/project-intent.md is the file the README names for that.

One thing the Quick Start does not cover: scaffolding a new project from the underlying template. That is a different command, `npx create-epicflare`, and it produces an epicflare project rather than a kody checkout.

The MCP surface is deliberately small, and that is a trade-off

Kody's design position is stated plainly: it "favors a compact MCP surface with powerful search and Code Mode execute flows over a large static tool catalog," and the scope section repeats it as a preference for "compact MCP surface area over a large static tool inventory."

This is the most consequential decision in the project, and it cuts both ways. A small surface means fewer tool definitions competing for context, and Code Mode execute means the agent writes code against the system rather than picking from a fixed menu. That scales better as capabilities grow, because you are not re-registering a tool for every new operation.

The cost is discoverability and predictability. With a static catalog, an operator can read the list and know exactly what the agent can do. With search plus execute, the set of reachable actions is bounded by what the runtime exposes and by whether the agent's search finds it. If you are evaluating kody for a compliance or audit use case where you need to enumerate capabilities up front, this architecture makes that harder, and the README does not offer an inventory document to compensate.

The README also names ChatGPT as "a likely primary host target, while keeping the server usable from other MCP hosts where practical." The phrase "where practical" is doing real work there. Portability across every MCP host is the marketing line, but the stated target is one host first.

Where kody is the wrong tool

The clearest limitation is the one the project states itself: kody is not a general-purpose agent harness. If your goal is to build an agent product, or to run arbitrary models against arbitrary tools, kody's opinionated structure (one assistant per user, packages, jobs, secrets, memories) will fight you.

A second constraint is the stack. The UI framework is Remix 3 in beta, per both the README table and the badge. Node 26 and TypeScript 6.0 are listed as the supported versions. That is a forward-leaning dependency set, and it means the project inherits the churn of a beta framework. The README does not document a rollback path for the beta UI dependency, and it does not describe a fallback if Remix 3 changes shape.

A third is operational. Running kody means running four Workers plus D1, KV and Durable Objects. That is a real Cloudflare footprint. The README's cloudflare-offerings document is described as covering "optional Cloudflare integrations," so some of it can be trimmed, but the worker fleet itself is the architecture, not an option. For a single user who just wants persistent notes for an agent, that is more infrastructure than the problem requires.

Finally, the README does not document rollback, backup or data export for a user's memories and secrets. Those are exactly the things you would want to get out of a system you are trusting with persistent assistant state, and their absence from the front page is worth noting before you commit real secrets to it.

How kody differs from a hosted MCP server or a plain agent framework

The obvious alternative is a hosted MCP server that ships memory and tooling as a service. The difference is control of the substrate. A hosted server owns the Durable Objects, the KV namespace and the D1 database; you get an endpoint. Kody gives you the deployment instead. You run the Workers, you hold the storage bindings, and the OAuth layer is yours. The trade is that you also own the upgrades, the Cloudflare bill and the failure modes.

A second alternative is a generic agent framework where you assemble memory, scheduling and secrets from libraries. Kody's difference there is that those pieces are already integrated around a multi-user isolation model and an MCP endpoint, so you are configuring rather than composing. You pay for that with the framework's opinions: the package runtime, the jobs worker and the Code Mode execute flow are the shape you get.

A third comparison worth making is against the epicflare starter the repo follows. The README says kody follows several epicflare conventions, and offers `npx create-epicflare` to scaffold a new project from that template. If what you actually want is the Cloudflare Workers plus Remix plus Nx foundation without the assistant semantics, the template is the smaller commitment. Kody is the template plus an opinionated assistant platform on top.

Licence, maintenance and what an upgrade actually costs

The package.json declares the licence as FSL-1.1-ALv2, which is the Functional Source License with an Apache 2.0 future licence. The repository's LICENSE file is the authoritative text, and the GitHub metadata reports the licence as NOASSERTION, meaning the platform's classifier could not match it to a known identifier. That mismatch is worth resolving yourself by reading the LICENSE file, because FSL is a source-available licence with usage restrictions rather than an OSI open source licence. This is not legal advice; if you plan to run kody commercially, read the terms.

The README also states that outside pull requests require a signed inbound Contributor License Agreement. That is a governance choice with a practical consequence: if you fork and want your changes upstreamed, you sign first.

On maintenance, the repository is not archived, and the last push was on 2026-09-10. Releases are dated and frequent: v2026.09.08, v2026.09.09 and v2026.09.10 all landed within three days of each other, and the release tag format is a calendar date. That cadence tells you upgrades are continuous rather than batched into stable majors, and it tells you the version number of any given deployment is a date, not a semantic version you can pin a compatibility promise to.

The upgrade cost follows from the architecture. Four Workers, D1, KV and Durable Objects mean a deploy touches several moving parts, and the deploy script in package.json runs tools/deploy.ts with an outdir and source-map upload, plus a prepare-e2e-env step when CLOUDFLARE_ENV is preview or test. There is no documented migration guide in the README for moving between daily releases.

Editorial conclusion

Adopt kody if you want a self-hosted, MCP-first assistant home where memory, secrets, packages and jobs are isolated per signed-in user, and you are comfortable deploying to Cloudflare Workers. Do not adopt it if you need a general-purpose agent harness, a stable non-beta UI stack, or a tool catalog you can extend without touching the repo. Before committing, verify three things: that your MCP host works against the OAuth-protected /mcp endpoint, that the FSL-1.1-ALv2 terms match how you intend to run the software, and that the packages/runtime-worker and packages/jobs-worker split fits your deployment budget.

Frequently asked questions

Official sources

1. Issues
2. kentcdodds/kody on GitHub
3. Project website
4. README
5. Releases