# The Kody factory map

Kody is a hosted factory for capabilities your assistant can discover, combine,
and keep running. Your assistant connects to Kody over MCP and starts with two
tools:

- **`search`** finds available capabilities, connected services, saved
  playbooks, official guides, and relevant memories. Search before building so
  the assistant can reuse what you already have.
- **`execute`** runs a temporary TypeScript module on Kody's servers. It can
  compose discovered capabilities, call connected services, and import exports
  from playbooks you own.

Those two doors lead to a set of user-isolated primitives.

## What is on the factory floor

### Secrets and integrations

**Secrets** are private credentials stored for your Kody account. Runtime code
refers to them by placeholder or an approved playbook mount; Kody does not
return the saved secret value to the assistant.

**Integrations** are saved connections to external services. OAuth-backed
integrations keep their token bundles server-side. Remote MCP servers expose
their tools through Kody. Search shows the capabilities available to the
signed-in user. Verify provider contracts against official documentation and
reuse or save narrow personal helpers for selected operations.

### Playbooks and `playbookStorage()`

**Playbooks** turn useful code into private, named executable behavior. Complete
text source lives in the application database. Save it with `playbookSave`, edit
using the token from `playbookGet`, and run current saved code in Kody's
isolated runtime. No separate activation or history exists.

Each playbook gets isolated durable **`playbookStorage()`** for runtime state
such as cursors, preferences, and checkpoints. Source configuration belongs in
playbook text files; credentials belong in secrets; changing runtime state
belongs in `playbookStorage()`.

### Jobs and schedules

**Jobs** run code later or on a schedule while your laptop is closed. A saved
playbook declares recurring schedules under `kody.jobs` so the schedule travels
with the playbook behavior. Deferred one-shot work uses
`workflows.create({ runAt })` from `execute` or playbook runtime. Playbook-job
runs stay on `/account/jobs`. Deferred workflow runs stay on
`/account/workflows`.

### Apps and webhooks

**Playbook apps** give a playbook a hosted HTTP and browser surface. They can
render a small app, receive requests, and use the same playbook runtime and
storage as its exports.

**Webhooks** give a playbook a public, credentialed inbound URL. A provider
sends an event to that URL, and Kody dispatches the validated request to the
playbook export that owns it. Apps are general hosted request surfaces; webhooks
are inbound event doors.

### Memories

**Memories** are durable facts and preferences attached to your Kody account.
Search can retrieve relevant memories as context for a task. Memory is for
information worth carrying between conversations, not playbook state, source
configuration, or credentials.

## The boundary around the factory

Hosted Kody cannot see your Mac's disk, your local Obsidian vault, local-only
CLI processes, `localhost`, or devices reachable only on your home network.
Installing a desktop MCP server does not make it reachable from Kody's
Cloudflare Workers.

To bring a local capability into the factory, run an MCP server beside the local
resource and expose that server through a protected public HTTPS route. The
[home MCP guide](/guides/local-mcp-tunnels) describes the Cloudflare Tunnel and
Access pattern and points at
[home-mcp-starter](https://github.com/kody-bot/home-mcp-starter). Then connect
its URL as a [remote MCP server](https://github.com/kentcdodds/kody/blob/main/docs/use/mcp-client-servers.md), and its tools
appear in search under `mcp:<name>`.

Work that does not fit a Worker isolate — a large npm graph, native code, or
multi-minute CPU — follows the same split: the saved playbook orchestrates, and
the owner operates the process. See
[Offload work that does not fit a Worker isolate](/guides/heavy-work-offload).

## A practical route through the map

1. Search for the outcome and inspect the exact capability shape.
2. Connect the needed secret, integration, or remote MCP server.
3. Use `execute` for a one-off composition and authenticated smoke test.
4. Reuse or save a personal playbook when the behavior should be reusable,
   reviewed, or scheduled.
5. Keep runtime state in `playbookStorage()` and expose only the app, webhook,
   export, or job surfaces the playbook needs. When the provider token is
   coarser than that surface, restrict grants and understand the remaining
   limits ([Gmail drafts without send](/guides/locked-gmail-drafts)).
6. Save a memory only when the user wants Kody to retain a durable fact or
   preference.

For the full ask-once-to-playbook loop, continue with
[How Kody works](/guides/how-kody-works). When playbooks, integrations, and MCP
servers look interchangeable, read
[Playbooks, integrations, and MCP servers](/guides/playbooks-integrations-mcp). For
playbook implementation details, load the
[playbook authoring guide](/guides/playbook-authoring).