# 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 packages,
  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 packages 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 package mount; Kody does not return
the saved secret value to the assistant. See [Secrets](/docs/secrets).

**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. For registry lookup, fork `@kody/integrations-sh`. For an
OpenAPI document, fork `@kody/openapi` and bind selected operations, or prefer a
close community helpers package.

### Packages and `packageStorage()`

**Packages** turn useful code into a named, versioned capability. Package source
lives in a repository, but published package code runs server-side in Kody's
runtime. A public package is not owned merely because it is visible: fork it to
create a saved package in your account, review it, and publish that owned copy
before adapting or invoking it as yours.

Each package gets isolated durable **`packageStorage()`** for runtime state such
as cursors, preferences, and checkpoints. Source and versioned configuration
belong in the package repository; credentials belong in secrets; changing
runtime state belongs in `packageStorage()`.

### Jobs and schedules

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

### Apps and webhooks

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

**Webhooks** give a package a public, credentialed inbound URL. A provider sends
an event to that URL, and Kody dispatches the validated request to the package
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 and between agents, not package
state, source configuration, or credentials. See [Shared memory](/docs/memory).

## 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](/docs/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 package orchestrates, and
the owner operates the process. See
[Offload work that does not fit a Worker isolate](/docs/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. Fork a close public package or author an owned package when the behavior
   should be reusable, reviewed, or scheduled.
5. Keep runtime state in `packageStorage()` and expose only the app, webhook,
   export, or job surfaces the package needs. When the provider token is coarser
   than that surface, lock the package
   ([Gmail drafts without send](/docs/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-package loop, continue with
[How Kody works](/docs/how-kody-works). When packages, integrations, and MCP
servers look interchangeable, read
[Packages, integrations, and MCP servers](/docs/packages-integrations-mcp). For
package implementation details, load the
[package authoring guide](/docs/package-authoring).