# Kody

> Kody is the home your agents share: connect the AI agent you already
> use over MCP and it gains durable memory, secrets it never reads, saved
> packages, jobs, workflows, webhooks, and apps that keep running while
> you are offline — and every other agent you connect reuses the same
> home.

Start with [What is Kody?](https://kody.codes/docs.md). Every doc below is
plain markdown; the same content is available to connected agents as
`search({ entity: "guide:{id}" })`.

## Introduction

What Kody is, the two MCP tools, and the loop those tools run.

- [What is Kody?](https://kody.codes/docs/what-is-kody.md) — Start here. Kody is the home your agents share — connect the AI agent you already use over MCP and it gains durable memory, secrets it never reads, saved packages, and jobs that keep running while you are offline. Covers what Kody is and is not, what you cannot get elsewhere, the building blocks, real uses, and notes for an agent running a discovery interview. Nothing here requires an account.
- [Search and execute](https://kody.codes/docs/search-and-execute.md) — Kody's MCP surface is two tools. search finds capabilities, guides, packages, integrations, and secrets. execute runs an ephemeral module that calls what you found. Covers how they work together and the inputs an agent actually passes.
- [How Kody works](https://kody.codes/docs/how-kody-works.md) — The factory loop as a conversation: ask what your favorite bot shipped, save the answer as an export you can invoke from any agent, then a daily email that stays quiet until something actually ships.
- [The Kody factory map](https://kody.codes/docs/kody-factory.md) — Map Kody's discovery, credentials, integrations, packages, storage, schedules, hosted surfaces, and memories—and know where the boundary is.

## Get started

Connect the agent you already use, make one useful thing, then reuse it from a second agent.

- [Connect your agent](https://kody.codes/docs/connect-your-agent.md) — The three-step Get started flow for people: connect the agent you already use over MCP, paste one prompt so that agent makes something useful in your account, then connect a second agent from another ecosystem and watch it reuse the same memory and package. Includes what approving access means, verified-email requirements, and which agents suit building versus using.
- [First run: the onboarding briefing](https://kody.codes/docs/onboarding.md) — First-run guide for a connected agent. Teach lightly what Kody is and is not, offer six concrete first-win choices, help them take one small win from their pick, and set up integrations with clear difficulty. Then Step 3.
- [First build: ad hoc execute, then persist](https://kody.codes/docs/quick-example.md) — Agent playbook after Make something useful (`/onboarding/step-2`) or Connect your agent (`/onboarding/step-1`): run one useful ad hoc execute, show the result, persist that working code as a package they own, and offer optional triggers without recommending one.
- [Second agent: reuse what already exists](https://kody.codes/docs/portability.md) — Second-agent proof after a first win. Find what the account already has, reuse it once, and stop. Retrieved as guide:portability from Step 3.
- [Email and memories: the welcome-email loop](https://kody.codes/docs/first-win.md) — Optional agent playbook: send a welcome email, point the person at their own inbox to reply, look the reply up when they say it is sent, save what matters as memories, then offer a next step. After Connect your agent (`/onboarding/step-1`), Step 2 is Make something useful (`/onboarding/step-2`) and Step 3 is Connect a second agent (`/onboarding/step-3`); the optional climax guide is quick-example. Load this when someone wants the email loop. Includes the no-polling rule and troubleshooting for missing mail and unbound tools.

## Concepts

The primitives every connected agent shares: memory, secrets, packages, triggers, and the runtime.

- [Shared memory](https://kody.codes/docs/memory.md) — What a Kody memory is, why it lives on the account instead of in one host's chat, how memories surface automatically on search and execute, the verify-first rule for writes, and what does not belong in memory (package state, config, credentials). Load this when someone asks what their agents remember about them or how memory travels between agents.
- [Secrets](https://kody.codes/docs/secrets.md) — How Kody lets your agent use your API keys, tokens, and private keys without ever reading them: the no-secret_get rule, `{{secret:name}}` placeholders resolved at the network boundary, host approval, package approval (website Allow links via `secretLock`), expiry, and where each kind of credential lives. Load this when someone asks how credentials work or whether the agent can see a key.
- [Custom secret providers](https://kody.codes/docs/secret-providers.md) — Use credentials from an external vault in secret-aware fetch without the agent ever reading them. Behind a feature flag; signed-in users can turn it on from this page.
- [Packages, integrations, and MCP servers](https://kody.codes/docs/packages-integrations-mcp.md) — Packages are saved behavior. Integrations are account-owned logins. MCP servers are how agents connect. Use this when those three look interchangeable.
- [Text your agent](https://kody.codes/docs/text-your-agent.md) — How to let a spouse or friend talk to *your agent* over a familiar chat surface (iMessage worked example). Surface vs brain vs tools: the agent holds the conversation; Kody is memory, secrets, packages, and jobs - not the chat buddy. Covers OpenClaw/Bezalel/Grok Bot patterns and a simpler SMS path with Twilio.
- [Jobs, workflows, and webhooks](https://kody.codes/docs/triggers.md) — How work runs when nobody is in the chat. Package-owned jobs for recurring schedules, workflows for deferred or long one-shot runs, inbound webhooks for provider events, subscriptions for events inside Kody, and the inbox — which to pick, how each is declared, and how to test one safely before enabling it. Load this when someone asks how to run something later, on a schedule, or when a provider knocks.
- [Runtime and efficiency](https://kody.codes/docs/platform-efficiency.md) — How unique Dynamic Worker days work across execute, jobs, package exports, and other surfaces, and how the acting user plus a stable module graph reuse one isolate per UTC day.

## Examples

Homepage trigger cards as worked examples: cron, webhook, email, and event.

- [Flake Hunter](https://kody.codes/docs/flake-hunter.md) — Homepage cron example: a package-owned daily job that scans CI for flaky end-to-end runs, stays quiet on a clean day, and only acts when a flake signal is present. Load this when someone asks how Flake Hunter works or how to hang a schedule on a package they own.
- [Sentry Issues](https://kody.codes/docs/sentry-issues.md) — Homepage webhook example: a package-owned inbound URL that accepts a Sentry issue POST, verifies HMAC on the platform, and starts triage without a model in the request path. Load this when someone asks how Sentry Issues works or how to hang a vendor webhook on a package they own.
- [Agent inbox](https://kody.codes/docs/agent-inbox.md) — Homepage email example: every account has a platform inbox, inbound mail emits email.message.received, and a package can wake work from a plus-tag without a model reading the mailbox. Load this when someone asks how Agent inbox works or how to treat email as a trigger.
- [Purchase thanks](https://kody.codes/docs/purchase-thanks.md) — Homepage event example: a verified purchase becomes a fact your factory already knows, and a package drafts a thank-you without anyone typing. Load this when someone asks how Purchase thanks works or how to react to an event Kody (or a package you own) already emitted.

## Packages

Turn working code into a package you own, then grow it.

- [Package lifecycle: reuse, execute, fork, or create](https://kody.codes/docs/package-lifecycle.md) — Choose between invoking existing behavior, temporary execute exploration, forking a close public package, deferred workflows, and creating a durable repo-backed package; test package-owned job wrappers safely.
- [Package authoring](https://kody.codes/docs/package-authoring.md) — START HERE when creating or materially changing a Kody package: package shape, required README.md (human) and AGENTS.md (agent), README Intent section, per-export JSDoc (search Purpose), personal-details hygiene before going public, secret-using package approval checklist, and scope-update guidance without adding new primitives.
- [Share a package with another person](https://kody.codes/docs/package-sharing.md) — Invite another paid Kody account to use one of your packages. Guests can read source and invoke, cannot publish or write, and must accept before the package attaches. Pin or follow published commits after accept.
- [Package apps](https://kody.codes/docs/package-apps.md) — Give a package a hosted Worker app on `*.kody.run`. Covers the fetch-handler contract, mount-stripped URLs, `packageContext` / `kody:runtime`, the platform-built browser client (`kody.app.client`) and static assets directory (`kody.app.assets`), session handoff, smoke tests with packageAppFetch, a Remix recipe (Example A), the same-origin proxy, lean forks, compiled clients, and listing verification.
- [Package subscriptions and events](https://kody.codes/docs/package-subscriptions.md) — Use package.json#kody.subscriptions for package-owned event handlers; discover subscribers with packageSubscriptionsList; smoke-test one handler from interactive MCP with packageSubscriptionDispatch; follow metadata-first email, run.error.recorded activity notifiers, integration.auth.failed / integration.auth.succeeded reconnect notifiers, mcp.server.disconnected / mcp.server.reconnected connection episodes, and repo / package lifecycle topics.
- [Offload work that does not fit a Worker isolate](https://kody.codes/docs/heavy-work-offload.md) — When package checks or publish rebuilds exceed isolate memory or CPU — usually a large npm graph such as PDF.js — keep the Kody package as a thin orchestrator and run the heavy work in a process the owner operates (Cloudflare Container, Fly machine, or similar). Do not provision paid infra without asking.

## Integrations

Bring your own keys, OAuth apps, OpenAPI documents, and MCP servers — and lock them to the code that should use them.

- [Integration bootstrap](https://kody.codes/docs/integration-bootstrap.md) — START HERE when a third-party integration must work before saving a dependent package or package app: inspect integration/secret state, stop for setup, run an authenticated smoke test, then communitySearch before building from scratch.
- [OAuth: bring your own app](https://kody.codes/docs/oauth.md) — START HERE for third-party OAuth: hosted /connect/oauth, the exact redirect URI (https://kody.codes/connect/oauth), required query params, PKCE vs confidential, the post-connect copyable agent prompt, and how it differs from MCP OAuth.
- [Google OAuth walkthrough](https://kody.codes/docs/google-oauth.md) — Interactive transcript of a coding agent walking a naive user through Google OAuth for Gmail inbox reading: official guides first, one console step at a time, prefilled /connect/oauth, refuse secrets in chat, then a Gmail profile smoke test.
- [Secret-backed integrations](https://kody.codes/docs/secret-backed-integration.md) — Default non-OAuth recipe for secret-backed integrations: research auth, collect secrets through /account/secrets/new, run a smoke test, build the downstream package, then surface package secret approval links (prefer bulk) before calling the work complete.
- [Secret setup URL reference](https://kody.codes/docs/account-secret-setup.md) — Hosted /account/secrets/new URL shape, query params, approval policy for API keys and PATs, and post-hoc package approval URLs including bulk approve.
- [OpenAPI integrations](https://kody.codes/docs/openapi-integrations.md) — Prefer a close community helpers package, then fork `@kody/openapi` to bind and call selected operations.
- [Connect a home MCP server](https://kody.codes/docs/local-mcp-tunnels.md) — Run an MCP server beside a vault, CLI, or home device, publish it with Cloudflare Tunnel and Access, and connect its HTTPS URL to Kody.
- [Lock an MCP server to a package](https://kody.codes/docs/locked-mcp-server.md) — Connected MCP servers expose every discovered tool to execute and every package. Lock the server to a thin package so only that published surface can call it.
- [Gmail drafts without send](https://kody.codes/docs/locked-gmail-drafts.md) — Google has gmail.send but no drafts-only scope. gmail.compose can manage drafts and send. Publish a drafts-only package, lock it, then integrationLock the connection so execute cannot use the token.

## Connect a provider

Verified, console-by-console walkthroughs for connecting a specific service.

- [Connect Discord](https://kody.codes/docs/discord.md) — Verified walkthrough for connecting Discord to Kody: the OAuth user-token lane for identity and server membership, the bot-token lane required for reading or posting in servers, 7-day rotating tokens, prefilled connect links, and users/@me smoke tests for both lanes.
- [Connect GitHub](https://kody.codes/docs/github.md) — Verified walkthrough for connecting GitHub to Kody: fine-grained personal access tokens, bring-your-own OAuth Apps, scope choices, prefilled connect links, and copy-paste smoke tests.
- [Connect Google (Gmail, Calendar, Drive)](https://kody.codes/docs/google.md) — Verified walkthrough for connecting Google to Kody: bring-your-own OAuth client, Google Auth Platform console steps, the Testing-status 7-day refresh-token trap, and a Calendar or Gmail smoke test.
- [Connect Notion](https://kody.codes/docs/notion.md) — Verified walkthrough for connecting Notion to Kody: the personal internal connection token lane (fastest), the public connection OAuth lane, the page-picker access model (Notion has no OAuth scopes), prefilled connect links, and a users/me smoke test for both lanes.
- [Connect Origin](https://kody.codes/docs/origin.md) — Verified walkthrough for connecting Cursor Origin to Kody: Origin Apps with Ed25519 signing keys, installation access tokens, the official helpers package, and a rate-limit smoke test. Cloud Agents API keys are not Origin credentials.
- [Connect Salesforce](https://kody.codes/docs/salesforce.md) — Verified connect walkthrough for Salesforce: bring-your-own Connected App or External Client App, the exact /connect/oauth callback, production vs sandbox login hosts, scopes, prefilled connect links, and a smoke test.
- [Connect Slack](https://kody.codes/docs/slack.md) — Verified walkthrough for connecting Slack to Kody with a user-token Slack app, then calling it from `@kody/slack`.
- [Connect Spotify](https://kody.codes/docs/spotify.md) — Verified walkthrough for connecting Spotify to Kody: dashboard app creation, the Development Mode Premium requirement and endpoint limits in force since February 2026, the PKCE public-client connect link, listening and playback scopes, and a profile smoke test.

## Help

When Kody gets in the way.

- [Report friction](https://kody.codes/docs/platform-friction.md) — Use for meaningful Kody friction, bugs, poor experiences, or suggestions: show the exact proposal and account-identity notification disclosure before asking for explicit approval, and write one actionable issue per submission (repro steps, expected vs actual, impact).

## Optional

- [Blog](https://kody.codes/blog): essays on owning your automations
- [Connect your agent (machine-readable)](https://kody.codes/auth.md): OAuth and MCP endpoint details