okengine 0.9.0 → 0.10.0

package/site/content/docs/recipes/llama-cpp.mdx

@@ -0,0 +1,153 @@
+---
+title: "llama.cpp"
+description: "Default local AI image — OpenAI-compatible llama-server, loopback-only publish, pinned build ≥ b8146."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+llama.cpp is the default `images.ai` pin for local inference. It runs
+`llama-server` with an OpenAI-compatible `/v1` API — lightest resource footprint
+for single-user / dev. Driver id stays `openai-compatible`.
+
+<Callout title="The one rule">
+  Pin a verified build ≥ `b8146`, publish only on loopback, and load models only from curated
+  registries (Docker Hub `ai/`) — never arbitrary untrusted GGUF.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  ai: { local: "openai-compatible", docker: "openai-compatible", test: "mock" },
+},
+images: {
+  ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // never :latest
+},
+```
+
+Or `oke ai setup --provider llama-cpp` (TTY: banner → Ultra Fast / Fast /
+Balanced / Smart → up to 20 curated Docker Hub `ai/` picks per tier) / `--yes`
+for `smollm2`.
+
+</Step>
+
+<Step>
+### Env written by the stack
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:8080/v1
+OKE_AI_MODEL=smollm2
+```
+
+`OKE_AI_MODEL` is a Docker Hub `ai/<id>` model. The recipe writes
+`docker/llama-entrypoint.py`, which Hub-pulls into the cache volume (native
+`llama download -dr`, then a CNCF `model.weight` fallback for newer tags like
+gemma4), then starts `llama-server -m <gguf> --alias <id>` (single-model — not
+router `--models-preset` / bare `--docker-repo`, which hang on b10290+). Never
+set `LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO` in the container env.
+
+`oke dev -d` shows the model id in the hero / Docker summary and polls
+`/v1/models` in the background until status is `ready` (first boot may take
+minutes while the Hub image downloads).
+
+</Step>
+
+<Step>
+### Ask through the OpenAI-compatible driver
+
+```typescript
+import { ai } from "okengine";
+
+export const smart = ai.model("smart", {
+  provider: "openai-compatible",
+  model: process.env.OKE_AI_MODEL ?? "smollm2",
+});
+```
+
+</Step>
+
+</Steps>
+
+## Security (hard requirements)
+
+| Control              | Requirement                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- |
+| Host publish         | `127.0.0.1:8080:8080` only — never `0.0.0.0`                                 |
+| Image pin            | Explicit build ≥ **b8146** (CVE-2026-27940 / CVE-2026-33298); never `latest` |
+| Model source         | Docker Hub [`ai/`](https://hub.docker.com/u/ai) namespace (or known HF GGUF) |
+| Untrusted GGUF       | **Forbidden** — crafted files can RCE the parser on unpatched builds         |
+| RPC / extra backends | Not published — OpenAI HTTP only                                             |
+
+Inside the container the server listens on `0.0.0.0` so the Compose network and
+loopback map work. The **host** bind is loopback — same isolation idea as
+Postgres/Redis, stricter on the published interface because of GGUF CVE risk.
+
+## Required env
+
+| Variable       | Required?         | Meaning                                 |
+| -------------- | ----------------- | --------------------------------------- |
+| `OKE_AI_URL`   | **Yes** in docker | Base URL including `/v1`                |
+| `OKE_AI_MODEL` | Recommended       | Docker Hub `ai/` id (default `smollm2`) |
+
+## What the recipe configures
+
+| Field          | Value                                                           |
+| -------------- | --------------------------------------------------------------- |
+| Container port | `8080`                                                          |
+| Host publish   | `127.0.0.1:8080:8080`                                           |
+| Healthcheck    | `GET /health`, every 5s, 24 retries, 900s start                 |
+| Connection URL | `http://host:8080/v1`                                           |
+| Model load     | `llama-entrypoint.py` → Hub pull (incl. CNCF weights) then `-m` |
+
+## When to choose something else
+
+| Workload                                   | Prefer                                  |
+| ------------------------------------------ | --------------------------------------- |
+| Single-user / dev, lightest footprint      | **llama.cpp** (this recipe)             |
+| Local DX with library pull UX              | [Ollama](/docs/recipes/ollama)          |
+| Multi-user / production concurrency on GPU | [vLLM](/docs/recipes/vllm)              |
+| Structured / agent workloads on GPU        | [SGLang](/docs/recipes/sglang)          |
+| Managed cloud                              | Anthropic / OpenAI / … (no `images.ai`) |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection refused on :8080">
+
+Confirm compose published `127.0.0.1:8080:8080` (not bare `8080:8080` on all
+interfaces). `OKE_AI_URL` must include `/v1`.
+
+</Accordion>
+<Accordion title="Model fails to load / slow first boot">
+
+First start Hub-pulls the curated `ai/` model into the named cache volume
+(see logs: `oke ai: ensuring…` / download %). Prefer `oke ai setup` tiers
+(Ultra Fast → `smollm2`) for smoke tests. Confirm `OKE_AI_MODEL` is active in
+`.env.local` / `docker/.env.docker`. Watch `oke dev` (`AI … — waiting…` →
+`ready`). If status stays `loading` forever on an old stack that still uses
+`--models-preset`, regenerate `docker/` and recreate AI. Newer Hub tags use
+CNCF weight layers — the entrypoint falls back when native `llama download`
+cannot find `vnd.docker.ai.gguf.v3`. Do not mount random GGUF files. Never put
+`LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO` in the container env.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [AI](/docs/elements/ai) — `fx.ask`, prompts, drivers
+- [Ollama](/docs/recipes/ollama) — fully supported alternative
+- [Environment variables](/docs/reference/environment-variables) — `OKE_AI_*`
+
+## Next
+
+<Cards>
+  <Card title="Ollama" description="Library UX alternative." href="/docs/recipes/ollama" />
+  <Card title="vLLM" description="Production GPU serving." href="/docs/recipes/vllm" />
+  <Card title="AI" description="Prompts, models, guardrails." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/recipes/mailpit.mdx

@@ -0,0 +1,136 @@
+---
+title: "Mailpit"
+description: "Local SMTP catcher for channel.email — SMTP_URL on :1025, UI on :8025, MAILPIT_UI_URL."
+icon: "Mail"
+source: "docs/spec/unified-theory.md"
+---
+
+Mailpit is the docker-mode email catcher — every message the `smtp` channel driver sends
+lands in a web UI instead of a real inbox. Pin it as `images["channel.email"]` when
+`drivers.channel.email.docker` is `smtp`.
+
+<Callout title="The one rule">
+  Docker ≈ prod for the **SMTP protocol** — same `SMTP_URL` shape. Mailpit is not a production MTA;
+  swap the image / URL for a real relay when you leave local docker.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image (templates already do)
+
+```typescript title="oke.config.ts"
+drivers: {
+  channel: {
+    email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+  },
+},
+images: {
+  "channel.email": "axllent/mailpit:v1.22.3",
+},
+```
+
+</Step>
+
+<Step>
+### Connect the smtp driver
+
+```bash title="docker/.env.docker (written by oke docker)"
+SMTP_URL=smtp://127.0.0.1:1025
+MAILPIT_UI_URL=http://127.0.0.1:8025
+```
+
+No `SMTP_USER` / `SMTP_PASSWORD` required for Mailpit's open local listener.
+
+</Step>
+
+<Step>
+### Send and inspect
+
+Trigger any flow that uses `fx.email` / channel email. Open `MAILPIT_UI_URL` (port
+**8025**) to read the caught message — subject, body, headers.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                      | Required?                  | Meaning                                                 |
+| ----------------------------- | -------------------------- | ------------------------------------------------------- |
+| `SMTP_URL`                    | **Yes** (app, smtp driver) | `smtp://host:1025` — boot fails without it              |
+| `OKE_CHANNEL_EMAIL_URL`       | Alternative                | Same role as `SMTP_URL`                                 |
+| `MAILPIT_UI_URL`              | Written by stack           | Browser UI — not read by the smtp driver                |
+| `SMTP_USER` / `SMTP_PASSWORD` | No for Mailpit             | Used when pointing `SMTP_URL` at an authenticated relay |
+
+## Data and backup
+
+Mailpit declares **no volume**. Caught messages live in container memory/disk for that
+instance only.
+
+**Backup means:** nothing durable to back up — this is a catcher. For forensic copies,
+export from the UI before recreate. Production mail never uses this image as the store of
+record.
+
+## Production note
+
+Templates set `prod: "smtp"` but still pin Mailpit in `images` for docker. In real prod,
+point `SMTP_URL` at your provider and set `SMTP_USER` / `SMTP_PASSWORD` as needed.
+
+Leaving Mailpit reachable on a public host exposes an open relay UI — bind to the compose
+network only.
+
+Healthcheck probes `http://127.0.0.1:8025/api/v1/info` — UI down ⇒ service unhealthy even
+if SMTP still accepts mail.
+
+## What the recipe configures
+
+| Field          | Value                                               |
+| -------------- | --------------------------------------------------- |
+| SMTP port      | `1025` (published)                                  |
+| Extra port     | `8025` → UI                                         |
+| Healthcheck    | `wget` against `/api/v1/info`, every 5s, 10 retries |
+| Connection URL | `smtp://host:1025`                                  |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: smtp driver needs SMTP_URL">
+
+The smtp binder refuses to start without `SMTP_URL` (or `OKE_CHANNEL_EMAIL_URL`). In
+docker mode the error asks whether `oke dev -d` wrote `docker/.env.docker`. Also rejects
+non-`smtp://` schemes: `oke boot: SMTP_URL must use smtp://`.
+
+</Accordion>
+<Accordion title="Messages send but UI is empty">
+
+Wrong UI port, or you opened a different instance's Mailpit. Confirm `MAILPIT_UI_URL`
+matches the published `8025` mapping for **this** compose project (instance-id offsets
+shift the host port).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Channel](/docs/elements/channel) — email delivery physics
+- [Environment variables](/docs/reference/environment-variables) — `SMTP_*` map
+- [Configuration](/docs/reference/configuration) — default `channel.email` image pin
+
+## Next
+
+<Cards>
+  <Card
+    title="RustFS"
+    description="S3-compatible files for the same stack."
+    href="/docs/recipes/rustfs"
+  />
+  <Card
+    title="OpenBao"
+    description="Vault recipe for docker/prod secrets."
+    href="/docs/recipes/openbao"
+  />
+  <Card title="Channel" description="How fx.email reaches humans." href="/docs/elements/channel" />
+</Cards>

package/site/content/docs/recipes/meilisearch.mdx

@@ -0,0 +1,139 @@
+---
+title: "Meilisearch"
+description: "Full-text store.index image — OKE_STORE_INDEX_URL, OKE_STORE_INDEX_KEY / MEILI_MASTER_KEY, /meili_data volume."
+icon: "Search"
+source: "docs/spec/unified-theory.md"
+---
+
+Meilisearch backs the `meilisearch` index driver — typo-tolerant full-text search over
+HTTP. Pin `images["store.index"]` and set `drivers.store.index` to `meilisearch` where
+you need it (index does **not** auto-promote in docker).
+
+<Callout title="The one rule">
+  Index stays `memory` in every environment until you set the driver map explicitly — there is no
+  silent docker fallback to Meilisearch or pgvector.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    index: { local: "memory", docker: "meilisearch", prod: "meilisearch" },
+  },
+},
+images: {
+  "store.index": "getmeili/meilisearch:v1.14",
+},
+```
+
+</Step>
+
+<Step>
+### Keys written by oke docker
+
+```bash title="docker/.env.docker"
+OKE_STORE_INDEX_URL=http://127.0.0.1:7700
+OKE_STORE_INDEX_KEY=…          # also accepted as MEILI_MASTER_KEY
+```
+
+Recipe injects into the container:
+
+- `MEILI_MASTER_KEY=${OKE_STORE_INDEX_KEY}`
+- `MEILI_ENV=${OKE_MEILI_ENV:-production}`
+- `MEILI_NO_ANALYTICS=true`
+
+</Step>
+
+<Step>
+### Search from a flow
+
+Use `store.index(…)` without `{ dims }` for full-text (vector dims select pgvector /
+libsql). Writes wait on Meilisearch tasks before returning.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable              | Required?            | Meaning                                          |
+| --------------------- | -------------------- | ------------------------------------------------ |
+| `OKE_STORE_INDEX_URL` | **Yes**              | Base URL — boot fails without it                 |
+| `OKE_STORE_INDEX_KEY` | **Yes** (production) | Master/API key; falls back to `MEILI_MASTER_KEY` |
+| `MEILI_MASTER_KEY`    | Alternate            | Same secret, container-side name                 |
+| `OKE_MEILI_ENV`       | Optional             | Passed as `MEILI_ENV` (default `production`)     |
+
+## Data and backup
+
+| Volume             | Path          | What it stores               |
+| ------------------ | ------------- | ---------------------------- |
+| `store-index-data` | `/meili_data` | Indexes, documents, settings |
+
+**Backup means:** snapshot/restore that named volume (or Meilisearch dumps). Recreating
+the container **keeps** data if the volume remains; deleting the volume wipes every index.
+
+The master key is **not** inside the volume — it lives in `.env.docker` / secrets.
+Losing the key without a backup blocks admin API access even if data remains.
+
+## Production note
+
+Always set a non-empty `OKE_STORE_INDEX_KEY` when `MEILI_ENV=production` — Meilisearch
+refuses insecure production mode without a master key. Prefer network isolation (compose
+network only) plus the key; do not publish `:7700` on the public internet without auth.
+
+Vector `ai.embed` into a meilisearch index fails loud — embeddings need `pgvector` /
+`libsql`, not FTS. See [Store · Index](/docs/elements/store#index).
+
+## What the recipe configures
+
+| Field          | Value                                          |
+| -------------- | ---------------------------------------------- |
+| Container port | `7700`                                         |
+| Healthcheck    | `wget` against `/health`, every 5s, 12 retries |
+| Connection URL | `http://host:7700`                             |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: meilisearch index needs OKE_STORE_INDEX_URL">
+
+No silent memory fallback. Re-run `oke dev --docker` or export `OKE_STORE_INDEX_URL`.
+Docker-mode wording asks whether `docker/.env.docker` was written.
+
+</Accordion>
+<Accordion title="meilisearch index: GET/POST … failed (403) — or master key errors">
+
+`OKE_STORE_INDEX_KEY` does not match `MEILI_MASTER_KEY` inside the container, or the key
+was rotated without updating the app env. Align both sides and restart. Unreachable host
+surfaces as `meilisearch index: unreachable at <url> — …`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Store · Index](/docs/elements/store#index) — FTS vs vector drivers
+- [Environment variables](/docs/reference/environment-variables) — index URL / key
+- [Configuration](/docs/reference/configuration) — `drivers.store.index` union
+
+## Next
+
+<Cards>
+  <Card
+    title="llama.cpp"
+    description="Default local AI for the same stack."
+    href="/docs/recipes/llama-cpp"
+  />
+  <Card
+    title="Postgres"
+    description="pgvector alternative for embeddings."
+    href="/docs/recipes/postgres"
+  />
+  <Card title="Store" description="Index facet API." href="/docs/elements/store" />
+</Cards>

package/site/content/docs/recipes/meta.json

@@ -0,0 +1,31 @@
+{
+  "title": "Recipes",
+  "icon": "Container",
+  "pages": [
+    "index",
+    "---SQL---",
+    "postgres",
+    "supabase-docker",
+    "cockroachdb",
+    "yugabytedb",
+    "timescale",
+    "---KV---",
+    "redis",
+    "valkey",
+    "dragonfly",
+    "---Proxy---",
+    "caddy",
+    "traefik",
+    "---Services---",
+    "pgdog",
+    "rustfs",
+    "mailpit",
+    "openbao",
+    "meilisearch",
+    "---AI---",
+    "llama-cpp",
+    "ollama",
+    "vllm",
+    "sglang"
+  ]
+}

package/site/content/docs/recipes/ollama.mdx

@@ -0,0 +1,142 @@
+---
+title: "Ollama"
+description: "Fully supported local AI alternative — OKE_AI_URL, pinned ≥ 0.17.1, loopback-only publish, library models only."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+Ollama remains a **fully supported** local model server (not deprecated). The
+default local pin is [llama.cpp](/docs/recipes/llama-cpp); choose Ollama when you
+want its library pull UX. Pin `images.ai` and set `drivers.ai` to `ollama`.
+
+<Callout title="The one rule">
+  Pin ≥ `0.17.1` (never `latest`), publish only on loopback, and load models only from Ollama’s
+  library — never arbitrary untrusted GGUF via `/api/create`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  ai: { local: "ollama", docker: "ollama", test: "mock" }, // prod: set deliberately
+},
+images: {
+  ai: "ollama/ollama:0.32.6", // never :latest — floor 0.17.1 (CVE-2026-7482)
+},
+```
+
+Or run `oke ai setup --provider ollama --yes`.
+
+</Step>
+
+<Step>
+### Env written by the stack
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:11434
+OKE_AI_MODEL=qwen3.5:9b
+```
+
+Host publish is `127.0.0.1:11434:11434`. Inside the container
+`OLLAMA_HOST=0.0.0.0:11434` so Docker networking works.
+
+</Step>
+
+<Step>
+### Boot pulls against the container API
+
+After compose is healthy, `oke dev -d` shows `OKE_AI_MODEL` in the hero / Docker
+summary, POSTs `/api/pull` to **this container’s**
+loopback URL when the recipe is Ollama — never a host `ollama` CLI.
+
+</Step>
+
+</Steps>
+
+## Security (hard requirements)
+
+| Control        | Requirement                                                                |
+| -------------- | -------------------------------------------------------------------------- |
+| Host publish   | `127.0.0.1:11434:11434` only — never `0.0.0.0`                             |
+| Image pin      | Explicit tag ≥ **0.17.1** (CVE-2026-7482); never `latest`                  |
+| Model source   | [Ollama library](https://ollama.com/library) only                          |
+| Untrusted GGUF | **Forbidden** — `/api/create` with crafted files is the CVE-2026-7482 path |
+
+Ollama and llama.cpp share GGUF-parser risk; Ollama also has its own Go loader
+CVE. Network exposure of `:11434` turns that into a remote attack.
+
+<Callout type="warn" title="Host `ollama` CLI is unrelated">
+  A host `ollama pull` often talks to a separately installed daemon. Trust boot ensure against
+  `OKE_AI_URL`.
+</Callout>
+
+## Required env
+
+| Variable                                     | Required?         | Meaning                                                            |
+| -------------------------------------------- | ----------------- | ------------------------------------------------------------------ |
+| `OKE_AI_URL`                                 | **Yes** in docker | Base URL — `oke boot: ollama driver needs OKE_AI_URL` when missing |
+| `OKE_AI_MODEL`                               | Recommended       | Model tag to pull/serve (default `qwen3.5:9b`)                     |
+| `OLLAMA_HOST`                                | Set by recipe     | `0.0.0.0:11434` inside the container                               |
+| `OKE_AI_VISION_MODEL` / `OKE_AI_EMBED_MODEL` | Optional          | Written by `oke ai setup` for logical models                       |
+
+## Data and backup
+
+| Volume    | Path            | What it stores                         |
+| --------- | --------------- | -------------------------------------- |
+| `ai-data` | `/root/.ollama` | Pulled model weights + Ollama metadata |
+
+## Production note
+
+Local Ollama is for docker/dev (and air-gapped prod you deliberately choose).
+For multi-user GPU self-hosting see [vLLM](/docs/recipes/vllm) /
+[SGLang](/docs/recipes/sglang). Cloud drivers stay separate.
+
+PII egress rules treat `ollama` as local — see [AI · PII](/docs/elements/ai).
+
+## What the recipe configures
+
+| Field          | Value                                          |
+| -------------- | ---------------------------------------------- |
+| Container port | `11434`                                        |
+| Host publish   | `127.0.0.1:11434:11434`                        |
+| Entrypoint     | Image default (`ollama serve`)                 |
+| Healthcheck    | `ollama list`, every 5s, 24 retries, 10s start |
+| Connection URL | `http://host:11434`                            |
+| Model pull     | Host-side `POST /api/pull` after healthy       |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="oke boot: ollama driver needs OKE_AI_URL">
+
+Docker mode expects `OKE_AI_URL` from `docker/.env.docker` when `images.ai` is pinned.
+Locally the default is `http://127.0.0.1:11434`. Prefer `oke ai setup` to wire everything
+in one pass.
+
+</Accordion>
+<Accordion title="Model missing / I already ran ollama pull on the host">
+
+The host CLI likely filled a **different** Ollama. Check `GET $OKE_AI_URL/api/tags`,
+then recreate with `oke dev -d`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [llama.cpp](/docs/recipes/llama-cpp) — default local AI
+- [AI](/docs/elements/ai) — `fx.ask`, prompts, evals
+- [CLI · oke ai setup](/docs/reference/cli) — non-interactive provider wiring
+
+## Next
+
+<Cards>
+  <Card title="llama.cpp" description="Default local AI." href="/docs/recipes/llama-cpp" />
+  <Card title="Meilisearch" description="Full-text index peer." href="/docs/recipes/meilisearch" />
+  <Card title="AI" description="Prompts, models, guardrails." href="/docs/elements/ai" />
+</Cards>