acrylblends 1.0.0 → 1.0.2

package/docs/framework/agents/index.md

@@ -33,6 +33,24 @@ The `agent` template (a Cordis app; `acryl-app` is its old name and still works)
 
 See [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md), [Plugin lifecycle](../cordis/plugin-lifecycle.md) and [Mounting](../cordis/mounting.md).
 
+## The agent panel and the terminals
+
+The panel is a chat button on every page of the running app, and `driver-pty` adds real terminals to it. Both are **development only** (see [what runs in production](../guides/production.md)). They need the rows of the `agent` template (`agent` and `extensions`, with the `model`, `tools` and `memory` the agent brings), so start from that template:
+
+```sh
+npm create acrylblends@latest my-app agent
+cd my-app
+npm install
+npx acrylblends add agent-panel driver-pty
+npm install
+npm run dev
+```
+
+- `add` puts the `agent-panel` row (and `driver-pty`'s after it) in `blend.yaml` before the `routes` row and registers both in `src/app.ts`. On an app without the `agent` and `extensions` rows, such as `blank`, it refuses before it copies anything and says which rows are missing.
+- **The panel's coding agents are yours.** `claude`, `codex` and `pi` run on the machine that runs the app, in the app folder, with the login of the person who started it: `claude` and `codex` use their own signed-in sessions, and `pi` is offered when `DEEPSEEK_API_KEY` is set or `pi` has stored a DeepSeek login (`~/.pi/agent/auth.json`). A program that is not installed, or is not logged in, is not offered; nothing is shared between machines, and a workshop laptop needs its own login. The panel's own `agent` (the offline scripted one) needs none.
+- `pi` has to be an executable on the `PATH`; a shell function that wraps the binary is fine as long as the binary itself is found by `which pi`.
+- `driver-pty` brings `node-pty`, which ships prebuilt binaries for macOS, Windows and Linux. npm 11 and pnpm warn that its install script was not run (they ask you to approve dependency install scripts); you can ignore the warning. If no `pty:` terminal is offered and the app prints why at start, approve and rebuild: `npm approve-scripts node-pty`, then `npm rebuild node-pty` (pnpm: `pnpm approve-builds`).
+
 ## Checking that an agent can use the docs
 
 The repository has a manual gate: it creates a fresh app, starts a headless coding agent inside it with a one-line task (for example "add a /customers/count route with a test"),

package/docs/framework/cordis/migration-to-1-0.md

@@ -7,12 +7,13 @@
 An app made by `acrylblends init` carries copies of the framework plugins (`acryl-router`, `acryl-node-server`, `acryl-door`, `extensions`, ...) in `plugins/`. `acrylblends upgrade` brings them to the version of the installed package:
 
 ```sh
-npm install acrylblends@latest        # in an app that depends on the package; the agent template does not
-npx acrylblends upgrade --dry-run     # what would change, and the diff of every file you edited
-npx acrylblends upgrade               # do it
+npx acrylblends@latest upgrade --dry-run   # what would change, and the diff of every file you edited
+npx acrylblends@latest upgrade             # do it
 npm install && npm run check && npm test
 ```
 
+**Write `@latest`.** A bare `npx acrylblends upgrade` runs the `acrylblends` the app has installed, and an app made before 1.0 has a 0.x copy with no `upgrade` verb. It does not upgrade anything: depending on the platform and the version it prints its old help and exits 0 (so nothing happens and nothing says so), or answers "unknown command" and exits 2. `npx acrylblends@latest` fetches the current package and runs that. (After the first upgrade the app depends on 1.x, and the bare form works too.)
+
 - A file nobody edited is replaced. A file the app edited stops the upgrade: nothing is changed, the diff of what would be lost is shown, and the command exits 1. Move your change out of the plugin (a plugin of your own in `plugins/<name>/` is never touched), or run `npx acrylblends upgrade --force`, which saves the edited versions in `.acrylblends/upgrade-backup/<time>/` before replacing them.
 - `--diff` prints the diff of every changed file, not only the edited ones. `acrylblends upgrade acryl-router extensions` upgrades only those plugins.
 - A file of your own inside a library plugin folder (a note, a test) is kept and reported. A plugin that a newer version needs and the app lacks is added.

package/docs/framework/getting-started/desktop.md

@@ -36,6 +36,26 @@ In a Blend app, the same two commands (`npx acrylblends add desktop`, `npm insta
 `npm install` does not download Electron's binary (Electron 44 has no install script). The first `npm run desktop` does: about 100 MB, once per machine, then it is cached. Behind a proxy or mirror set `ELECTRON_MIRROR`
 (and `ELECTRON_CACHE` to reuse a download); if the download is blocked, run `npx install-electron` where the mirror is reachable.
 
+## Linux: Ubuntu 23.10 and later
+
+Ubuntu 23.10 and later restrict unprivileged user namespaces (`kernel.apparmor_restrict_unprivileged_userns=1`). Chromium's sandbox needs them, and an Electron unpacked by npm into `node_modules` has no AppArmor profile, so Electron stops at the start with "The SUID sandbox helper binary was found, but is not configured correctly" before the app runs.
+
+`npm run desktop` starts through `plugins/desktop/launch.ts`, which reads that sysctl. **Only when it is `1` on Linux** it starts Electron with `--no-sandbox` and prints one line saying so; on macOS, on Windows and on any Linux without the restriction Electron starts with its sandbox, as it always does. The window's renderer is still locked down (context isolation, no Node in the page, web security); what is lost is Chromium's process sandbox around it.
+
+To keep the sandbox, give Electron an AppArmor profile that allows `userns`, as the VS Code and Chrome `.deb` packages do. Save this as `/etc/apparmor.d/my-app-electron` (the path is the one in your app's `node_modules`), then `sudo apparmor_parser -r /etc/apparmor.d/my-app-electron`:
+
+```text
+abi <abi/4.0>,
+include <tunables/global>
+
+profile my-app-electron /path/to/my-app/node_modules/electron/dist/electron flags=(unconfined) {
+  userns,
+  include if exists <local/my-app-electron>
+}
+```
+
+The launcher then still sees the sysctl as `1` and passes `--no-sandbox`; set `ACRYLBLENDS_DESKTOP_SANDBOX=1` to start with the sandbox anyway.
+
 ## A different start page
 
 The window opens on `/`. To open another path, set it in `package.json`: `"acrylblends": { "desktopPath": "/todo" }`.

package/docs/framework/guides/create-acrylblends.md

@@ -54,6 +54,8 @@ bun create acrylblends@latest my-app --template nodejs
 | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
 | `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
+| `--from <id \| source>` | A starter from the registry by its id (`acrylblends.notes-desktop`), or any source above. Only starters that declare `runtime: acrylblends` are made; an ACRYL app starter is refused. See [Starters from the registry](#starters-from-the-registry). | `-- --from acrylblends.notes-desktop` |
+| `--registry <source>` | Read the ids from this registry instead of the public one: `github:owner/repo` or a folder, with an `index.json` (at its root or in `registry/`). | `-- --from login.thing --registry github:acryldev/workshop-2026-11-20` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |
@@ -61,6 +63,25 @@ bun create acrylblends@latest my-app --template nodejs
 
 The templates are inside the package, so creating a project needs no network except for `--install`.
 
+## Starters from the registry
+
+The [registry](https://acrylblends.github.io/blends) lists starters people published. Each is a whole app (`blend.yaml`, `plugins/`, `src/`, `package.json`, `README.md`) that other people can start from, and its index says which runtime it is for:
+
+```sh
+npm create acrylblends@latest my-notes -- --from acrylblends.notes-desktop
+cd my-notes
+npm install
+npm run dev
+```
+
+- npm needs the `--` before `--from`; with `pnpm`, `yarn` and `bun` it is not needed.
+- A starter with `runtime: acrylblends` is an `acrylblends` app: this command downloads its folder, gives the manifest to the new app (`metadata.id: acrylblends.my-notes`, `visibility: private`; the starter's id and licence stay the starter's), checks it for anything that looks like a secret, and writes it. Nothing in it is installed or run: `npm install` is yours to run, and the dependencies of the starter (a desktop starter brings `electron`) are in its `package.json`.
+- A starter for the ACRYL app (`runtime: acryl`, the older `acryl.*` entries) is refused with one line that says so, because its plugins run only inside the ACRYL app. Nothing is written.
+- An unknown id lists the starters this command can make.
+- The ids come from `https://acrylblends.github.io/registry/index.json`. `--registry github:owner/repo` reads another registry with the same layout (`index.json` and `blends/<id>/`), a team's own or a workshop's; `--registry ./folder` reads one on disk.
+
+To publish a starter of your own, see [the registry README](https://github.com/acrylblends/acrylblends.github.io/tree/main/registry): the folder of your app under `blends/<id>/` with an `acryl.template.json`, in a pull request.
+
 ## Templates from a repository or a package
 
 A second argument after the directory makes the app from someone else's template:

package/docs/framework/guides/production.md

@@ -10,14 +10,27 @@
 | **The door** (`acryl-door`: `.acryl/bin/acryl`, the page script, the operator routes) | **experimental**: starts when the server is up | starts nothing: no service, no route, no `.acryl/` folder, no script in the page. `ACRYL_DOOR=off` also turns it off. A host that means to run it in production sets `allowInProduction: true` in the plugin's config |
 | **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
 | **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
-| **Live plugin install** (`extensions`, `builder`) | **experimental**: install, update, remove and reload plugins while the app runs | the `nodejs`, `notes` and `chat` templates leave the `extensions` row out; the `agent` template does not (see below) |
+| **Live plugin install and the agent** (`extensions`, `builder`, `agent`: `POST /ask`) | **experimental**: install, update, remove and reload plugins while the app runs; the agent builds them | left out: the `nodejs`, `notes` and `chat` templates drop the `extensions` row, and the `agent` template drops `agent`, `builder` and `extensions` (since 1.0.1) unless `ACRYL_PRODUCTION_KEEP` names them |
+| **The chat template's model endpoint** (`POST /api/chat`) | answers anyone | **closed** (503) unless `CHAT_ACCESS_TOKEN` is set, or `ACRYL_PRODUCTION_KEEP=chat` makes it public with a warning and a per-address limit (since 1.0.2) |
 | `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
 
 Experimental means: it works and is gated, its interface may still change in a minor version, and it is not for the public internet. The door and the panel are loopback and own-page only, with a per-run secret and an audit log; that is a convenience fence for a developer's machine, not an authentication system.
 
-## The `agent` template is a development app
+## The `agent` template in production
 
-The `agent` template mounts an agent behind `POST /ask` that can write plugins into the running app (`builder`) and install them (`extensions`). Only its door is left out in production. Do not deploy it as it is: remove the `agent`, `builder` and `extensions` rows from `blend.yaml` (or start from `blank`, `nodejs`, `notes`, `chat` or `todo`), and if live install is wanted anywhere shared, set `approval: true` so an install waits for `POST /extensions/approve`.
+The `agent` template mounts an agent behind `POST /ask` that spends the model key and can write plugins into the running app (`builder`) and install them (`extensions`, with `POST /extensions/approve` deciding installs). **None of that is behind a login.** Since 1.0.1, with `NODE_ENV=production` the template leaves the `agent`, `builder` and `extensions` rows out, along with the door: `/ask`, `/extensions*` and `/tasks*` are not mounted, and the page and `GET /health` stay. 1.0.0 left them mounted.
+
+- To keep a row anyway, name it: `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` (a comma list). Each row kept prints a `WARNING` line at start saying what it gives a visitor. Put your own login in front before you do.
+- **An app made by 1.0.0 keeps its own `src/app.ts` and `src/routes.ts`**, which `acrylblends upgrade` never touches (they are your files). Until you change them: deploy with the `agent`, `builder` and `extensions` rows set to `disabled: true` in `blend.yaml`, or start from another template, or copy the new `src/app.ts` and `src/routes.ts` of a fresh `acrylblends init my-app --template agent` over yours.
+
+## The `chat` template in production
+
+The chat template answers with the owner's model key, so anyone who can reach it spends that key. Since 1.0.2, with `NODE_ENV=production` it is **closed**: every route but `GET /health` answers 503 until you choose one of:
+
+- `CHAT_ACCESS_TOKEN=<a long random string>`: the browser asks for a login and takes any user name with the token as the password. Share the token with the people who may use the chat.
+- `ACRYL_PRODUCTION_KEEP=chat`: the chat is public, with a `WARNING` line at start and a limit of `CHAT_RATE_PER_MINUTE` messages a minute from one address (default 20; behind a proxy you run, set `TRUST_PROXY=1` so the limit counts the visitor, not the proxy). Prefer your own login in front.
+
+An app made by 1.0.0 or 1.0.1 keeps its own `src/routes.ts`: copy `src/access.ts`, `src/chat-app.ts` and `src/routes.ts` from a fresh `acrylblends init my-app --template chat`, or put a login in front.
 
 ## What live plugin install does and does not promise
 
@@ -38,6 +51,6 @@ Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the buil
 ## Checklist for a deployment
 
 1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
-2. Start from a template that is not `agent`, or remove the agent rows.
+2. With the `agent` template, leave `ACRYL_PRODUCTION_KEEP` unset (1.0.1 and later), or remove the agent rows. With the `chat` template, set `CHAT_ACCESS_TOKEN` (1.0.2 and later) or put your own login in front.
 3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
 4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",

package/plugins/agent-panel/headless.ts

@@ -1,5 +1,8 @@
 /** The panel's own drivers, all `chat`: the app's agent, and the coding agents (`claude`, `codex`, `pi`) started headless in the app folder. */
 import { spawn, spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { ChatDriver, ChatEvent } from './drivers.ts'
 
@@ -62,11 +65,30 @@ export function onPath(program: string): boolean {
   return found.status === 0
 }
 
-/** The headless programs this machine can offer: installed (pi also needs its key in the environment). */
+/** Whether pi can reach DeepSeek: the key in the environment, or the one pi stored for itself when its owner logged in (`~/.pi/agent/auth.json`, a `deepseek` entry). */
+export function piHasDeepseekKey(
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+): boolean {
+  if (env.DEEPSEEK_API_KEY) return true
+  try {
+    const stored = JSON.parse(
+      readFileSync(
+        join(env.PI_CODING_AGENT_DIR ?? join(home, '.pi', 'agent'), 'auth.json'),
+        'utf8',
+      ),
+    ) as Record<string, { key?: unknown } | undefined>
+    return typeof stored.deepseek?.key === 'string' && stored.deepseek.key !== ''
+  } catch {
+    return false
+  }
+}
+
+/** The headless programs this machine can offer: installed (an executable on the PATH; a wrapper function around it is fine) and, for pi, able to reach its model. */
 export function availableHeadless(wanted?: readonly HeadlessName[]): HeadlessName[] {
   const found: HeadlessName[] = []
   for (const driver of wanted ?? (['claude', 'codex', 'pi'] as const)) {
-    if (driver === 'pi' && !process.env.DEEPSEEK_API_KEY) continue
+    if (driver === 'pi' && !piHasDeepseekKey()) continue
     if (onPath(driver)) found.push(driver)
   }
   return found

package/plugins/desktop/launch.ts

@@ -0,0 +1,48 @@
+/**
+ * `npm run desktop`: starts Electron on `main.ts` next to this file. It exists for one case: on Linux where the kernel restricts unprivileged user namespaces
+ * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
+ * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
+ */
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
+export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
+
+/** Whether the sandbox cannot start here: Linux, with the restriction on. `read` returns a file's text, or throws when there is none. */
+export function sandboxBlocked(
+  platform: string,
+  read: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): boolean {
+  if (platform !== 'linux') return false
+  try {
+    return read(RESTRICT_USERNS).trim() === '1'
+  } catch {
+    return false
+  }
+}
+
+export const SANDBOX_NOTICE =
+  "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
+  'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
+
+/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
+export function electronArgs(entry: string, blocked: boolean): string[] {
+  return blocked ? ['--no-sandbox', entry] : [entry]
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const electron = createRequire(import.meta.url)('electron') as string
+  // ACRYLBLENDS_DESKTOP_SANDBOX=1: the owner has given Electron an AppArmor profile and wants the sandbox.
+  const blocked =
+    process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
+  if (blocked) console.warn(SANDBOX_NOTICE)
+  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
+    stdio: 'inherit',
+  })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}

package/plugins/desktop/plugin.json

@@ -9,7 +9,7 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron plugins/desktop/main.ts"
+    "desktop": "node plugins/desktop/launch.ts"
   },
   "omit": ["**/*.test.*"],
   "mount": "nothing to mount: run `npm install`, then `npm run desktop` (the window opens on the app's own server; every electron call is in plugins/desktop)"

package/plugins/desktop-web/launch.ts

@@ -0,0 +1,48 @@
+/**
+ * `npm run desktop`: starts Electron on `main.ts` next to this file. It exists for one case: on Linux where the kernel restricts unprivileged user namespaces
+ * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
+ * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
+ */
+import { spawn } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
+export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
+
+/** Whether the sandbox cannot start here: Linux, with the restriction on. `read` returns a file's text, or throws when there is none. */
+export function sandboxBlocked(
+  platform: string,
+  read: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): boolean {
+  if (platform !== 'linux') return false
+  try {
+    return read(RESTRICT_USERNS).trim() === '1'
+  } catch {
+    return false
+  }
+}
+
+export const SANDBOX_NOTICE =
+  "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
+  'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
+
+/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
+export function electronArgs(entry: string, blocked: boolean): string[] {
+  return blocked ? ['--no-sandbox', entry] : [entry]
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const electron = createRequire(import.meta.url)('electron') as string
+  // ACRYLBLENDS_DESKTOP_SANDBOX=1: the owner has given Electron an AppArmor profile and wants the sandbox.
+  const blocked =
+    process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
+  if (blocked) console.warn(SANDBOX_NOTICE)
+  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
+    stdio: 'inherit',
+  })
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+}

package/plugins/desktop-web/plugin.json

@@ -9,7 +9,7 @@
     "electron": "44.9.3"
   },
   "scripts": {
-    "desktop": "electron plugins/desktop-web/main.ts"
+    "desktop": "node plugins/desktop-web/launch.ts"
   },
   "gitignore": [".acrylblends/"],
   "omit": ["**/*.test.*"],

package/templates/agent/AGENTS.md

@@ -4,3 +4,5 @@
 Besides `src/routes.ts`, the app runs an agent (`POST /ask`) that can write plugins into `plugins/` while the app runs and install them with
 rollback; `GET /extensions` and `GET /tasks` show what it did. A plugin there is a folder with an `index.ts` exporting `name`, `inject`, `apply(ctx)`
 and an optional `check(ctx)` that receives the plugin's own context (so `ctx.router` reads as in `apply`). It may import `acryl-router`.
+
+**Production.** The agent, the builder and the extensions are development tools: `POST /ask` spends the model key and runs tools, a plugin installed live runs in this process, and none of it is behind a login. With `NODE_ENV=production` `src/app.ts` leaves those three rows out, so `/ask`, `/extensions*` and `/tasks*` are not mounted; the page and `GET /health` stay. `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` keeps the named rows, and each one kept prints a `WARNING` line at start.

package/templates/agent/src/app.ts

@@ -62,6 +62,14 @@ export interface App {
   stop(): Promise<void>
 }
 
+/** The development rows production leaves out, and what each one gives a visitor. */
+const DEVELOPMENT_ROWS: Record<string, string> = {
+  agent: 'POST /ask runs the agent, which spends the model key and calls its tools',
+  builder: 'the agent can write plugin source into plugins/',
+  extensions:
+    'a plugin installed live runs in this process, and POST /extensions/approve decides installs',
+}
+
 /**
  * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The app's `plugins/`
  * folder is trusted to install at start, and is where the builder writes.
@@ -84,6 +92,29 @@ export async function createApp(
   if (!listen) leaveOut.add('acryl-node-server').add('acryl-door')
   if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off')
     leaveOut.add('acryl-door')
+  // Production: the rows that give a visitor power over the running app or the owner's model key are left out too. The agent (`POST /ask` spends the model key and runs tools),
+  // the builder and the extensions (live plugin install runs code in this process, and `POST /extensions/approve` decides it) are development tools. `ACRYL_PRODUCTION_KEEP`
+  // names the ones to keep (`agent,builder,extensions`); each one kept is announced at start, because none of them is behind a login.
+  if (process.env.NODE_ENV === 'production') {
+    const keep = new Set(
+      (process.env.ACRYL_PRODUCTION_KEEP ?? '')
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name !== ''),
+    )
+    for (const name of keep)
+      if (!(name in DEVELOPMENT_ROWS))
+        console.warn(
+          `WARNING: ACRYL_PRODUCTION_KEEP names "${name}", which is not one of ${Object.keys(DEVELOPMENT_ROWS).join(', ')}`,
+        )
+    for (const [row, danger] of Object.entries(DEVELOPMENT_ROWS)) {
+      if (keep.has(row))
+        console.warn(
+          `WARNING: the "${row}" row runs in production because ACRYL_PRODUCTION_KEEP names it: ${danger}. Nothing here is behind a login; put the app behind your own.`,
+        )
+      else leaveOut.add(row)
+    }
+  }
   const manifest = {
     ...read,
     plugins: read.plugins.map((row) => (leaveOut.has(row.use) ? { ...row, disabled: true } : row)),

package/templates/agent/src/routes.ts

@@ -14,13 +14,14 @@ const DOOR_TAG =
     : ''
 
 /**
- * The app's own routes on the router: `POST /ask` for the agent; `GET /extensions` and `GET /tasks` to observe what it did (every run is a
- * durable task owning one task per tool call); `POST /tasks/cancel`. What changes is also streamed: `GET /api/state/tasks/events` and
- * `GET /api/state/extensions/events`. The mount is removed when the plugin is disposed.
+ * The app's own routes on the router. Always: the page and `GET /health`. While the agent, the extensions and the task recorder run: `POST /ask` for the agent; `GET /extensions`
+ * (and `POST /extensions/approve` and `/deny`) and `GET /tasks` to observe and steer what it did (every run is a durable task owning one task per tool call); `POST /tasks/cancel`.
+ * What changes is also streamed: `GET /api/state/tasks/events` and `GET /api/state/extensions/events`. In production `src/app.ts` leaves the agent, builder and extensions rows
+ * out (unless `ACRYL_PRODUCTION_KEEP` names them), and then those routes are not mounted at all. The mounts are removed when the plugin is disposed.
  */
 export const routes = {
   name: 'routes',
-  inject: ['router', 'agent', 'extensions', 'tasks'],
+  inject: ['router'],
   apply(ctx: Context) {
     // A body here is a name, an id or a question; anything bigger is refused before it is read.
     const json = async (c: {
@@ -29,48 +30,54 @@ export const routes = {
       const body = await c.req.json().catch(() => undefined)
       return typeof body === 'object' && body !== null ? (body as Record<string, unknown>) : {}
     }
-    const app = new Acryl()
-      .use(bodyLimit({ maxSize: 64 * 1024 }))
+    const limit = bodyLimit({ maxSize: 64 * 1024 })
+    const base = new Acryl()
+      .use(limit)
       // A browser gets a page (the door's and the agent panel's script tags are added where they are mounted); everything else gets the JSON.
       .get('/', (c) =>
         (c.req.header('accept') ?? '').includes('text/html')
           ? c.html(
-              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title></head><body><h1>${APP_NAME}</h1><p>This app runs an agent. Ask it for a feature (<code>POST /ask</code>), or add the chat panel with <code>npx acrylblends add agent-panel</code>.</p>${DOOR_TAG}</body></html>`,
+              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title></head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). Ask it for a feature (<code>POST /ask</code>), or add the chat panel with <code>npx acrylblends add agent-panel</code>.</p>${DOOR_TAG}</body></html>`,
             )
           : c.json({ app: APP_NAME, ok: true }),
       )
       .get('/health', (c) => c.json({ ok: true }))
-      .get('/extensions', (c) =>
+    ctx.router.route('/', base)
+    // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
+    ctx.inject(['agent', 'extensions', 'tasks'], (inner) => {
+      const app = new Acryl().use(limit).get('/extensions', (c) =>
         c.json({
-          installed: ctx.extensions.list(),
-          notInstalled: ctx.extensions.pending(),
-          waitingForApproval: ctx.extensions.approvals(),
+          installed: inner.extensions.list(),
+          notInstalled: inner.extensions.pending(),
+          waitingForApproval: inner.extensions.approvals(),
         }),
       )
-    // The owner's decision on an install that is waiting (the `approval` parameter in blend.yaml).
-    for (const [path, decide] of [
-      ['/extensions/approve', (name: string) => ctx.extensions.approve(name)],
-      ['/extensions/deny', (name: string) => ctx.extensions.deny(name)],
-    ] as const) {
-      app.post(path, async (c) => {
-        const { name } = await json(c)
-        if (typeof name !== 'string') return c.json({ error: 'name must be a string' }, 400)
-        return c.json(await decide(name))
-      })
-    }
-    app
-      .get('/tasks', (c) => c.json(ctx.tasks.list().slice(0, 100)))
-      .post('/tasks/cancel', async (c) => {
-        const { id } = await json(c)
-        if (typeof id !== 'string' || !ctx.tasks.get(id))
-          return c.json({ error: 'no such task' }, 404)
-        return c.json({ cancelled: ctx.tasks.cancel(id) })
-      })
-      .post('/ask', async (c) => {
-        const { question } = await json(c)
-        if (typeof question !== 'string') return c.json({ error: 'question must be a string' }, 400)
-        return c.json(await ctx.agent.run(question))
-      })
-    ctx.router.route('/', app)
+      // The owner's decision on an install that is waiting (the `approval` parameter in blend.yaml).
+      for (const [path, decide] of [
+        ['/extensions/approve', (name: string) => inner.extensions.approve(name)],
+        ['/extensions/deny', (name: string) => inner.extensions.deny(name)],
+      ] as const) {
+        app.post(path, async (c) => {
+          const { name } = await json(c)
+          if (typeof name !== 'string') return c.json({ error: 'name must be a string' }, 400)
+          return c.json(await decide(name))
+        })
+      }
+      app
+        .get('/tasks', (c) => c.json(inner.tasks.list().slice(0, 100)))
+        .post('/tasks/cancel', async (c) => {
+          const { id } = await json(c)
+          if (typeof id !== 'string' || !inner.tasks.get(id))
+            return c.json({ error: 'no such task' }, 404)
+          return c.json({ cancelled: inner.tasks.cancel(id) })
+        })
+        .post('/ask', async (c) => {
+          const { question } = await json(c)
+          if (typeof question !== 'string')
+            return c.json({ error: 'question must be a string' }, 400)
+          return c.json(await inner.agent.run(question))
+        })
+      inner.router.route('/', app)
+    })
   },
 }

package/templates/agent/test/app.test.ts

@@ -65,3 +65,77 @@ test('stops listening when stopped', { skip }, async () => {
   await assert.rejects(fetch(`${app.url}/health`))
   await rm(home, { recursive: true, force: true })
 })
+
+/** Boot in a given environment, with the warnings collected. */
+async function inEnvironment(
+  env: Record<string, string | undefined>,
+  run: (app: App, warnings: string[]) => Promise<void>,
+) {
+  const saved = Object.fromEntries(Object.keys(env).map((key) => [key, process.env[key]]))
+  const warnings: string[] = []
+  const warn = console.warn
+  console.warn = (message: unknown) => void warnings.push(String(message))
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) delete process.env[key]
+    else process.env[key] = value
+  }
+  try {
+    await withApp((app) => run(app, warnings))
+  } finally {
+    console.warn = warn
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+  }
+}
+
+const asking = (app: App) =>
+  app.root.router.request('/ask', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ question: 'add 2 3' }),
+  })
+
+test('in production the agent, the builder and the extensions are left out: no /ask, no live install, no approve route; the page and /health stay', () =>
+  inEnvironment({ NODE_ENV: 'production', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
+    assert.equal((await app.root.router.request('/health')).status, 200)
+    assert.equal((await app.root.router.request('/')).status, 200)
+    for (const [path, method] of [
+      ['/ask', 'POST'],
+      ['/extensions', 'GET'],
+      ['/extensions/approve', 'POST'],
+      ['/tasks', 'GET'],
+    ] as const) {
+      const response = await app.root.router.request(path, { method })
+      assert.equal(response.status, 404, `${method} ${path} answered ${response.status}`)
+      await response.body?.cancel()
+    }
+    assert.equal((app.root as unknown as { agent?: unknown }).agent, undefined)
+    assert.equal((app.root as unknown as { extensions?: unknown }).extensions, undefined)
+  }))
+
+test('ACRYL_PRODUCTION_KEEP keeps the named rows in production and says so at start; a name it does not know is reported', () =>
+  inEnvironment(
+    { NODE_ENV: 'production', ACRYL_PRODUCTION_KEEP: 'agent,extensions,nope' },
+    async (app, warnings) => {
+      const answer = await asking(app)
+      assert.equal(answer.status, 200)
+      assert.equal(((await answer.json()) as { status: string }).status, 'completed')
+      assert.equal((await app.root.router.request('/extensions')).status, 200)
+      assert.ok(
+        warnings.some((line) => line.includes('"agent" row runs in production')),
+        warnings.join('\n'),
+      )
+      assert.ok(warnings.some((line) => line.includes('"extensions" row runs in production')))
+      assert.ok(!warnings.some((line) => line.includes('"builder" row runs in production')))
+      assert.ok(warnings.some((line) => line.includes('names "nope"')))
+    },
+  ))
+
+test('outside production nothing changes: the agent answers and the extensions route is there', () =>
+  inEnvironment({ NODE_ENV: 'test', ACRYL_PRODUCTION_KEEP: undefined }, async (app, warnings) => {
+    assert.equal((await asking(app)).status, 200)
+    assert.equal((await app.root.router.request('/extensions')).status, 200)
+    assert.deepEqual(warnings, [])
+  }))

package/templates/chat/AGENTS.md

@@ -13,4 +13,4 @@ A Cordis app: `blend.yaml` lists the plugins that are mounted (`acryl-router`, `
 
 ## Before you ship
 
-Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key: put it behind a login or on a private network before it is public.
+Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key, so with `NODE_ENV=production` the chat is **closed**: every route but `GET /health` answers 503 (`src/access.ts`). Set `CHAT_ACCESS_TOKEN` (the browser asks for it; any user name, the token as the password), or name the chat in `ACRYL_PRODUCTION_KEEP=chat` to make it public on purpose: that prints a `WARNING` at start and limits one address to `CHAT_RATE_PER_MINUTE` messages a minute (default 20). Prefer your own login in front of a public chat.