# Recipes and the local runtime

> A recipe is the reproducible local execution contract for a model or piece of code. Turn a GitHub repository or a Hugging Face model into one, run it on your own machine, and drive it from a node in Kaitoi Studio.

Source: https://kaitoi.io/docs/cli/recipes/
Section: Kaitoi CLI
Written for: Anyone running models locally, or connecting local services to Kaitoi Studio.
Prerequisites: Kaitoi CLI installed and logged in
Last reviewed: 2026-09-16

---

A **recipe** is the reproducible local execution contract for a model or a piece
of code: where it comes from, what it needs, which inputs it accepts and which
outputs it returns. A **node** is the graph-facing interface that calls that
recipe through Runtime.

That separation is the point. The recipe pins how something runs on your
machine; the node is how a graph talks to it.

## Running recipes

The runtime runs installed recipes locally. From the CLI:

```bash
kaitoi runtime list
kaitoi runtime install <recipe>
kaitoi runtime run <recipe>
kaitoi runtime serve
```

Or from Kaitoi Code, in plain language:

```text
You > list my available runtime recipes
You > run the gemma recipe with a short test prompt
You > save the runtime output into this workspace
```

Code actions that execute code, install or uninstall packages, or start or stop
the runtime all require confirmation.

## Turning a repository into a node

### 1. Generate the recipe

Point the generator at a GitHub repository or a Hugging Face model:

```bash
kaitoi runtime generate https://github.com/owner/repository -o my-recipe.yaml
```

```bash
kaitoi runtime generate https://huggingface.co/owner/model -o my-recipe.yaml
```

This produces a recipe YAML file and a companion Python script.

Generation calls a model, and there are two ways it can be paid for. Generating
from the `kaitoi` dashboard uses your Kaitoi login: the call goes through
Kaitoi's managed provider and is billed to your Kaitoi account, so there is no
key to configure. You have to be signed in; the dashboard says so if you are
not.

Running `kaitoi runtime generate` straight from the command line does not go
through Kaitoi. It calls Anthropic directly and needs your own key, passed as
`--api-key` or set in the runtime config:

```bash
kaitoi runtime config set anthropic_api_key sk-ant-...
```

Review the generated code before running it, exactly as you would review any
code downloaded from a repository.

### 2. Validate and test locally

```bash
kaitoi runtime validate ./my-recipe.yaml
kaitoi runtime info ./my-recipe.yaml
```

Pass the input flags the generated recipe declares. A text recipe might take:

```bash
kaitoi runtime run ./my-recipe.yaml --prompt "A small launch test"
```

When the result looks right, install it so Runtime and Kaitoi Studio can
discover it:

```bash
kaitoi runtime install ./my-recipe.yaml
kaitoi runtime packages
```

### 3. Start Runtime and connect it

```bash
kaitoi up
```

`kaitoi up` starts the Runtime server and its Kaitoi connection together. Check
both are healthy with `kaitoi status`.

### 4. Create the node in Kaitoi Studio

1. Open **Settings → Integrations → Runtime**.
2. Confirm Runtime shows **Connected** and find the installed recipe.
3. Choose **Create Node** beside that recipe.
4. Penny reads the recipe schema, creates typed inputs and outputs, wires the
   call through Runtime, and adds the node to your graph.
5. Run the node once with a small input before using it in a larger graph.

To write the node yourself, declare which recipe it covers and accept the
`runtime` helper as an injected argument:

```python
# @node title="My Local Recipe" category="Local" icon="cpu" preview=true
# @task category="Create" subcategory="Text" filter="Local Runtime"
# @input string prompt label="Prompt" widget=multiLine default=""
# @output string text label="Result"
# @api runtime recipe="my-recipe"

def run(prompt, runtime):
    result = runtime.run_recipe("my-recipe", {"prompt": prompt})
    text_files = result.get("outputs", {}).get("text", [])
    if not text_files:
        return {"@error": "The recipe did not produce text."}
    return {"text": runtime.download_text(text_files[0]).strip()}
```

The exact input names and output keys come from your recipe. For file inputs use
`runtime.upload(...)`; for generated files use `runtime.download(...)` or one of
the bounded text and JSON download helpers. A node created through **Create
Node** handles those mappings for you.

## Connecting local services

Use Connect when you want Kaitoi Studio to reach services running on your
computer. Several can be connected at once: starting Blender does not replace
your Runtime or Ollama connection.

```bash
kaitoi up          # start runtime and tunnel it to Kaitoi
kaitoi status      # check what is connected
```

Tunnel a specific service:

```bash
kaitoi connect runtime
kaitoi connect ollama
kaitoi connect comfyui
kaitoi connect blender
```

Tunnel any local port:

```bash
kaitoi tunnel 3000 --name my-app
```

Stop local tunnels and runtime processes:

```bash
kaitoi stop
```

## Current limitations

- If the Runtime connection is unavailable, Kaitoi Studio cannot start a new
  recipe run or receive its result. Check `kaitoi status` before starting a long
  graph run.
- Recipe generation from the command line calls Anthropic directly and needs
  your own key. Only the dashboard path is billed to your Kaitoi account.