Document container config DB, on-wake restarts, and CLI scope

advanced/container-runtime.mdx

@@ -45,7 +45,7 @@
 | Health check | `docker info` | `container system status` |
 | Platform | macOS, Linux, Windows (WSL2) | macOS 15+ only |
 
 ### Switching runtimes
 
 Run the `/convert-to-apple-container` skill in Claude Code. To revert, use `git revert`.
 
@@ -57,15 +57,15 @@
 - **Bun** (pinned to 1.3.12) — runs agent-runner TypeScript directly (no compilation)
 - **Chromium** — browser automation via agent-browser
 - **Claude Code SDK** — `@anthropic-ai/claude-code` installed globally via pnpm
 - **tini** — PID 1 signal forwarding (ensures outbound.db writes finalize on SIGTERM)
 - **pnpm** (via corepack) — for global Node CLI installs
 - **System tools** — `curl`, `git`, `ca-certificates`, `unzip`
 - **Optional CJK fonts** — `fonts-noto-cjk` (~200 MB, opt-in via `INSTALL_CJK_FONTS=true`)
 
 ### Key design decisions
 
 - **Source is NOT baked in** — `/app/src` is a read-only bind mount from the host. Source changes never require an image rebuild.
 - **`only-built-dependencies` allowlist** in `.npmrc` for `agent-browser` and `@anthropic-ai/claude-code`
 - **Runs as `node` user** (non-root) with `/workspace/group` as working directory
 - **Entrypoint**: `tini -> entrypoint.sh -> exec bun run /app/src/index.ts`
 
@@ -77,12 +77,14 @@
 
 ### Per-agent-group images
 
-Agent groups can specify custom packages in `container.json`. The host builds a derived Docker image:
+Each agent group has a row in the `container_configs` table holding its custom apt and npm package lists. The host builds a derived Docker image:
 
 - Tag: derived from the checkout-scoped base image and agent group
 - Built on top of `nanoclaw-agent-v2-<slug>:latest`
 - Adds custom apt and npm packages
 
+Manage the package lists with `ncl groups config add-package` / `remove-package`. Restart the running container with `ncl groups restart --id <group-id> --rebuild` to apply changes — package CLI operations no longer auto-kill containers.
+
 ## Two-database IO model
 
 In v2, all communication between host and container uses two SQLite databases per session. There is no stdin/stdout piping, no IPC files, and no output markers.
@@ -94,7 +96,7 @@
 | `messages_in` | Inbound messages, tasks, system notifications |
 | `delivered` | Tracks delivery outcomes for outbound message IDs |
 | `destinations` | Live destination map (channels and other agents) |
 | `session_routing` | Default reply routing (channel_type, platform_id, thread_id) |
 
 ### outbound.db (container writes, host reads)
 
@@ -109,7 +111,7 @@
 
 Three invariants are critical for correctness:
 
 1. **`journal_mode=DELETE`** — WAL's mmapped `-shm` doesn't refresh across Docker mounts
 2. **Host opens-writes-closes per operation** — closing invalidates the container's page cache
 3. **One writer per file** — DELETE-mode journal unlink isn't atomic across the mount
 
@@ -117,11 +119,11 @@
 
 ### Spawning containers
 
 Containers are spawned by the `spawnContainer` function. Wake calls are deduplicated via an in-flight promise map.
 
 <Steps>
   <Step title="Read agent group config">
-    The host reads `container.json` and resolves provider contributions.
+    The host reads the agent group's row from the `container_configs` table, materializes a snapshot to `container.json` for the container to read, and resolves provider contributions.
   </Step>
 
   <Step title="Build volume mounts">
@@ -151,13 +153,13 @@
 |------|---------------|------|---------|
 | Session folder | `/workspace` | RW | inbound.db, outbound.db, outbox/, inbox/ |
 | Agent group folder | `/workspace/agent` | RW | Working files |
-| container.json | `/workspace/agent/container.json` | RO | Nested read-only config |
+| container.json | `/workspace/agent/container.json` | RO | Materialized snapshot of the `container_configs` row |
 | Composed CLAUDE.md | `/workspace/agent/CLAUDE.md` | RO | Regenerated each spawn |
 | Global memory | `/workspace/global` | RO | Shared instructions |
 | Agent-runner source | `/app/src` | RO | Bind mount from host |
 | Container skills | `/app/skills` | RO | Shared skill definitions |
 | Claude SDK state | `/home/node/.claude` | RW | SDK state + skill symlinks |
 | Additional mounts | `/workspace/extra/{name}` | Per-config | Validated against allowlist |
 | Provider mounts | Various | Per-provider | Provider-contributed |
 
 ### Timeouts and stale detection
@@ -165,13 +167,28 @@
 Containers have two timeout/detection mechanisms:
 
 1. **Container timeout** — maximum runtime before force kill (default: 30 minutes)
 2. **Stale detection** — host sweep checks `.heartbeat` mtime and `processing_ack` age to detect stuck containers
 
 ### Container shutdown
 
 - `killContainer(sessionId, reason)` stops the container via `docker stop`, falls back to SIGKILL
+- An optional `onExit` callback fires after the container process exits — used by restart flows to guarantee the old container is fully gone before respawn
 - On close/error, the session is marked stopped and typing indicators are cleared
 
+### Explicit restart and on-wake messages
+
+Container restart is always explicit — config CLI operations do not auto-kill containers. Use the admin CLI:
+
+```bash
+ncl groups restart --id <group-id> [--rebuild] [--message "context for the agent"]
+```
+
+- `--message` writes an on-wake message that is only delivered to the fresh container's first poll iteration (via the `on_wake` flag on `messages_in`)
+- `--rebuild` rebuilds the per-agent-group image first
+- From inside a container, `--id` is auto-filled and only the calling session is restarted
+
+The on-wake mechanism eliminates the race where a dying container — still in its SIGTERM grace period — could steal the message intended for its replacement. Self-mod approval handlers (`install_packages`, `add_mcp_server`) use the same flow.
+
 ## Credential injection
 
 The OneCLI SDK's `applyContainerConfig()` configures each container's network to route through the vault:
@@ -204,7 +221,7 @@
 
 <Accordion title="Inspect container mounts">
   ```bash
   docker inspect nanoclaw-{session-id} | jq '.[0].Mounts'
   ```
 </Accordion>
 

api/configuration.mdx

@@ -4,11 +4,11 @@
 tag: "UPDATED"
 ---
 
-NanoClaw configuration is managed through environment variables, the `.env` file, and the `src/config.ts` module. In v2, some configuration has moved to `container.json` per agent group.
+NanoClaw configuration is managed through environment variables, the `.env` file, and the `src/config.ts` module. In v2, per-agent-group runtime config (provider, model, packages, MCP servers, mounts, `cli_scope`) lives in the `container_configs` table in the central DB, managed via the `ncl` admin CLI. Existing `groups/<folder>/container.json` files from earlier installs are backfilled into the DB automatically on startup; the file is still materialized at spawn time so the container runner can read it.
 
 ## Environment variables
 
 Configuration is read from `.env` file or `process.env`, with hardcoded fallbacks.
 
 <ParamField path="ASSISTANT_NAME" type="string" default="Andy">
   Name of the assistant. Used in trigger pattern and message routing.
@@ -55,7 +55,7 @@
 </ParamField>
 
 <ParamField path="TZ" type="string" default="system timezone">
   Timezone for scheduled tasks (cron expressions). Resolved from `TZ` env, `.env` file, then system default. Validated as a real IANA timezone identifier. Falls back to `UTC` if no valid timezone is found.
 </ParamField>
 
 ## Timezone configuration
@@ -67,7 +67,7 @@
 3. `Intl.DateTimeFormat().resolvedOptions().timeZone` (system default)
 4. `'UTC'` (fallback)
 
 Each candidate is validated as a real IANA timezone identifier before being accepted. This affects cron expression evaluation for scheduled tasks.
 
 ## Directory paths
 
@@ -90,7 +90,7 @@
 </ResponseField>
 
 <ResponseField name="MOUNT_ALLOWLIST_PATH" type="string">
   `~/.config/nanoclaw/mount-allowlist.json` — mount security allowlist (never mounted into containers)
 </ResponseField>
 
 ## Trigger pattern
@@ -135,5 +135,5 @@
 - **Secrets** are never read by NanoClaw directly — OneCLI manages them externally
 - The OneCLI Agent Vault injects credentials into container API traffic at request time
 - Containers cannot extract real credentials from the vault
 - Mount allowlist is stored outside the project root and never mounted into containers
 - The `.env` file is read by the config module for NanoClaw settings only (not for API keys)

api/group-management.mdx

@@ -1,10 +1,10 @@
 ---
 title: Group management
 description: API reference for agent groups, messaging groups, wirings, and the v2 entity model
 tag: "UPDATED"
 ---
 
 In v2, NanoClaw uses a new entity model that separates agent groups (workspaces) from messaging groups (platform chats). These are connected through wirings — many-to-many relationships stored in `messaging_group_agents`.
 
 ## Entity model
 
@@ -23,7 +23,7 @@
 ```
 
 - Each agent group has a folder under `groups/{folder}/`
-- Container configuration lives on disk (`container.json`), not in the database
+- Container configuration lives in the `container_configs` table in the central DB (provider, model, packages, MCP servers, mounts, `cli_scope`); a snapshot is materialized to `container.json` at spawn time
 - Each gets its own OneCLI agent identifier for credential scoping
 
 ### Messaging groups
@@ -45,9 +45,9 @@
 - Auto-created on first mention or DM
 - `denied_at` silently drops future mentions
 
 ### Wirings (messaging_group_agents)
 
 Wirings connect messaging groups to agent groups:
 
 ```typescript
 interface MessagingGroupAgent {
@@ -128,9 +128,10 @@
 | Table | Purpose |
 |-------|---------|
 | `agent_groups` | Agent workspaces |
+| `container_configs` | Per-agent-group runtime config (provider, model, packages, MCP servers, mounts, `cli_scope`) |
 | `messaging_groups` | Platform chats/channels |
 | `messaging_group_agents` | Wirings with engage/scope/session config |
 | `users` | Namespaced platform identifiers |
 | `user_roles` | Owner and admin roles |
 | `agent_group_members` | Unprivileged membership |
 | `user_dms` | Cached DM channel mapping |
@@ -160,15 +161,30 @@
 | `session_state` | Persistent key/value store |
 | `container_state` | Tool-in-flight tracking |
 
+## Admin CLI (`ncl groups`)
+
+The `ncl` admin CLI exposes group and container-config management. Write operations require approval from inside containers; on the host they run directly.
+
+| Verb | Purpose |
+|------|---------|
+| `list`, `get`, `create`, `update`, `delete` | Standard CRUD over `agent_groups` |
+| `restart` | Kill containers for a group; pass `--rebuild` to rebuild the image and `--message <text>` to deliver an on-wake message to the fresh container |
+| `config get` | Show the container config row |
+| `config update` | Update scalar fields (`--provider`, `--model`, `--effort`, `--image-tag`, `--assistant-name`, `--max-messages-per-prompt`, `--cli-scope`) |
+| `config add-mcp-server` / `config remove-mcp-server` | Manage the MCP servers attached to a group |
+| `config add-package` / `config remove-package` | Manage apt and npm package lists |
+
+Config CLI operations no longer auto-kill containers — call `ncl groups restart` explicitly to apply changes. Group-scoped agents (where `cli_scope = 'group'`) cannot change `cli_scope` on themselves or any other group.
+
 ## Channel approval flow
 
 When a message arrives on an unwired channel:
 
 1. Router detects no wirings exist for this messaging group
 2. Channel-request gate sends approval card to the owner
 3. **Approve** — creates wiring with defaults:
    - Groups: `mention-sticky` engage mode
    - DMs: `pattern='.'` (always respond)
    - Triggering sender is auto-admitted as a member
    - Original event is replayed
 4. **Deny** — sets `denied_at` on the messaging group

changelog/docs-updates.mdx

@@ -5,20 +5,33 @@
 rss: true
 ---
 
+<Update label="Container config in DB, on-wake restarts, CLI scope" description="2026-05-09" tags={["Updated"]}>
+  Documented three v2.0.46–v2.0.48 features that change how per-agent-group config is stored and how containers are restarted.
+
+  ## Updated
+  - **`concepts/containers`**: container config now lives in `container_configs` (DB), not `container.json`; the file is a spawn-time snapshot. Added explicit-restart and on-wake message section. MCP server and package management commands now reference `ncl groups config`.
+  - **`concepts/groups`**: agent group definition references the `container_configs` row. New "CLI scope" section covering `disabled` / `group` / `global` and escalation blocks.
+  - **`api/configuration`**: per-agent-group runtime config moved to the central DB; `container.json` is materialized on spawn.
+  - **`api/group-management`**: added `container_configs` table to schema. New "Admin CLI (`ncl groups`)" section listing all verbs and behavior.
+  - **`advanced/container-runtime`**: spawn flow reads `container_configs`; `killContainer` exposes an `onExit` callback. New "Explicit restart and on-wake messages" section.
+  - **`features/customization`**: mount config moved to the `additional_mounts` column of `container_configs`.
+  - **`changelog/index`**: added v2.0.45 (admin CLI, v1→v2 migration) and v2.0.48 (DB-backed config, on-wake, CLI scope) release entries.
+</Update>
+
 <Update label="v2.0.0 launch readiness: front-door rewrites" description="2026-04-22" tags={["Updated"]}>
   Phase A of the v2 documentation sprint — bringing the pages every new user lands on into alignment with the v2 rewrite. All claims verified directly against upstream source (`src/db/schema.ts`, `src/types.ts`, `src/config.ts`, `container/Dockerfile`, `src/delivery.ts`) rather than upstream `docs/` (which includes a stale `architecture.md` draft and a `db-session.md` that omits the `container_state` table).
 
   ## Rewritten
   - **`introduction.mdx`**: v2 positioning — two-DB session IO, entity model, Node + Bun runtime split, OneCLI-only credentials. Token count updated to ~127k (~64% of context window). Source file table aligned with `src/` as of v2.0.1.
   - **`quickstart.mdx`**: one-command `bash nanoclaw.sh` flow replaces the v1 fork-and-clone + Claude Code + `/setup` dance. Documents the three-level setup log contract (terminal, `logs/setup.log`, per-step raw logs) and the Anthropic OAuth exception.
   - **`installation.mdx`**: simplified to system requirements + platform prerequisites + `bash nanoclaw.sh`. Service management retained (launchd / systemd / WSL wrapper). File-structure tree updated for `data/v2-sessions/`, `store/v2.db`, and the per-session `inbound.db` + `outbound.db` layout.
   - **`integrations/overview.mdx`**: reframed around channels (13+) and providers (4), both living on dedicated branches (`channels`, `providers`). Expanded channel list to cover Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, Resend, and the local `/claw` CLI.
   - **`features/customization.mdx`**: full v2 rewrite — verified trigger pattern code against `src/config.ts`, replaced nonexistent `POLL_INTERVAL` / `SCHEDULER_POLL_INTERVAL` with actual `ACTIVE_POLL_MS` / `SWEEP_POLL_MS` from `src/delivery.ts`, documented per-wiring engage config (`engage_mode`, `sender_scope`, `ignored_message_policy`, `session_mode`), kept OneCLI / legacy credential proxy as version tabs.
 
   ## v2 update banners
   Added `<Warning>` banners to pages pending a v2 rewrite (channel adapters moved to a single `channels` branch in v2, not per-channel `skill/*` branches):
   - `integrations/whatsapp.mdx`, `telegram.mdx`, `discord.mdx`, `slack.mdx`, `gmail.mdx`, `x-twitter.mdx`, `skills-system.mdx`
   - `integrations/ollama.mdx` (Ollama now lives on the `providers` branch — `/add-ollama-provider` or `/add-ollama-tool`)
 
   ## Token count sync
   - `integrations/skills-system.mdx`: 43.8k → 127k
@@ -26,15 +39,15 @@
 </Update>
 
 <Update label="v2.0.0: architectural rewrite docs" description="2026-04-22" tags={["Updated"]}>
   Merged PR #187 — comprehensive rewrite of concepts, advanced, api, and features pages for the v2.0.0 ground-up architectural rewrite ([qwibitai/nanoclaw#1919](https://github.com/qwibitai/nanoclaw/pull/1919)). Closed PRs #184, #185, #186 as superseded.
 
   ## Updated
   - **Two-database session model**: `inbound.db` (host writes) + `outbound.db` (container writes) replace stdin/stdout piping and filesystem IPC — documented across `concepts/architecture`, `advanced/ipc-system`, `advanced/container-runtime`
   - **Entity model**: agent groups, messaging groups, wirings (many-to-many), users, and roles replace the v1 group/channel model — new `concepts/groups` and `api/group-management`
   - **Bun-based agent runner**: runs TypeScript directly (no compilation), shared source via read-only bind mount, `tini` as PID 1 — `concepts/containers`, `advanced/container-runtime`
   - **Permissions system**: engage modes (pattern/mention/mention-sticky), sender scope (all/known), unknown sender policies (strict/request_approval/public), approval flows — `concepts/security`, `advanced/security-model`
   - **Delivery system**: two-poll architecture (active 1s, sweep 60s) with delivery action registry — `features/messaging`
   - **Task model**: tasks as `messages_in` rows with cron recurrence and series tracking — `concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`
   - **OneCLI Agent Vault** is the sole credential path; legacy credential proxy removed — `advanced/security-model`, `api/configuration`
   - **Changelog**: v2.0.0 release entry
 
@@ -59,14 +72,14 @@
   - **Architecture**: Documented auto-compact threshold at 165k tokens
 </Update>
 
 <Update label="v1.2.46–v1.2.47 sync: store mount, reply context, requiresTrigger" description="2026-04-04" tags={["Updated"]}>
   Triaged 3 automated Mintlify PRs (#175–#177). Merged #177 (most comprehensive), closed #175 and #176 (superseded). Cherry-picked unique content from closed PRs.
 
   ## Updated
   - **Store mount (rw)**: Documented `store/` read-write mount for main agent across containers, container-runtime, security, security-model, groups, customization pages
   - **`requiresTrigger` parameter**: Added to `register_group` MCP tool description in containers and messaging pages
   - **Reply context**: Updated architecture database section with `reply_to_message_id`, `reply_to_message_content`, `reply_to_sender_name` columns
   - **`isMain` preservation**: Updated register_group handler snippet in messaging page
   - **`CONTAINER_MAX_OUTPUT_SIZE`**: Added truncation behavior note to configuration reference
   - **Token count**: Updated from 43.3k to 43.4k in introduction and skills-system pages
   - **Changelog**: Added v1.2.46 and v1.2.47 product release entries
@@ -87,11 +100,11 @@
 </Update>
 
 <Update label="PR triage: v1.2.43–v1.2.46 sync" description="2026-04-02" tags={["Updated"]}>
   Reviewed and triaged 8 automated Mintlify PRs (#161–#168). Merged 4, closed 4 (superseded or stale token counts). Validated all changes against upstream source code at v1.2.46. Deleted 11 stale branches (4 PR + 7 orphan).
 
   ## Updated
   - **OneCLI version labels**: Corrected Agent Vault version from v1.2.22+ to v1.2.35+ across 8 pages, added tabbed 401 troubleshooting
   - **Ollama integration**: Added 4 admin tools (`ollama_pull_model`, `ollama_delete_model`, `ollama_show_model`, `ollama_list_running`) gated by `OLLAMA_ADMIN_TOOLS=true`, noted Ollama removal from core
   - **Stale session recovery**: Added auto-recovery docs to troubleshooting and container-runtime lifecycle, plus manual sqlite3 fallback
   - **Container runtime**: Documented `hostGatewayArgs()`, `--add-host` flag, `curl`/`git` in container image
   - **SDK options**: Added `settingSources` and `sender` parameter docs
@@ -104,23 +117,23 @@
   Merged automated health check PR #158 (4 of 5 fixes verified against upstream). Corrected the remaining inaccurate claim in a follow-up (#159).
 
   ## Fixed
   - **`api/message-routing`**: Removed phantom `channel?: ChannelType` param from `formatOutbound` signature
   - **`features/scheduled-tasks`**: Updated TIMEZONE snippet to current `resolveConfigTimezone()` with IANA validation and UTC fallback
   - **`advanced/container-runtime`**: Fixed `stopContainer` code from async `exec()` callback to actual sync try/catch pattern
   - **`api/configuration`**: Added `trace` as valid `LOG_LEVEL` value (used by container runner for verbose output)
   - **`features/messaging`**: Corrected stale `src/session-commands.ts` reference to `src/index.ts`, and fixed misleading description of what `index.ts` does
 
   ## Updated
   - **`advanced/remote-control`**: Fixed inaccurate security section — the remote control URL requires Anthropic sign-in, not just URL secrecy. Based on feedback from Gavriel Cohen.
 </Update>
 
 <Update label="Automated PR triage: v1.2.35–v1.2.42 sync" description="2026-03-28" tags={["Updated", "Fixed"]}>
   Reviewed and triaged 27 automated Mintlify PRs (#92–#151). Merged 6, consolidated 7 into a single verified PR (#153), closed 15 (superseded, fabricated, or conflicting). Validated all changes against upstream source code at v1.2.42. Deleted 41 stale `mintlify/*` branches.
 
   ## Updated
   - **OneCLI rebrand**: Renamed "OneCLI Gateway" to "OneCLI Agent Vault" across 15 pages, updated URL to `github.com/onecli/onecli`. Code snippets preserved as-is (upstream source still uses "gateway" in code).
   - **Message limits**: Corrected 200-message cap to `MAX_MESSAGES_PER_PROMPT` (default 10) across messaging, architecture, and configuration pages
   - **Dependencies**: Removed phantom deps (`pino`, `pino-pretty`, `yaml`, `zod`), updated `better-sqlite3` to `11.10.0` and `cron-parser` to `5.5.0`
   - **Token count**: Updated from ~41.3k to ~42.4k
   - **Mount property**: Fixed `containerConfig.mounts` → `additionalMounts` with `hostPath`
   - **SQL column**: Fixed `trigger` → `trigger_pattern` in troubleshooting query
@@ -130,9 +143,9 @@
   - **Telegram forum topics** (`integrations/telegram`) — `message_thread_id` tracking and automatic topic routing
   - **Task scripts cost guidance** (`concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`) — API credit awareness, testing guidance, when-not-to-use advice
   - **Auth 401 troubleshooting** (`advanced/troubleshooting`) — short-lived vs long-lived OAuth tokens, `claude setup-token` fix
   - **K8s image GC** (`advanced/troubleshooting`) — Rancher Desktop kubelet garbage collection known issue
   - **Text-style formatting** (`features/messaging`) — corrected WhatsApp link rendering and Telegram Markdown v1 preservation
   - **Security fixes** (`advanced/container-runtime`, `advanced/security-model`, `concepts/security`) — `stopContainer` name validation, mount path colon rejection, `isMain` preservation, allowlist caching behavior
   - **Configuration**: Added `MAX_MESSAGES_PER_PROMPT` and `LOG_LEVEL` environment variables
   - **Skills**: Added `/init-onecli` (operational) and `/add-emacs` (upstream)
 
@@ -143,7 +156,7 @@
 </Update>
 
 <Update label="Automated PR triage: v1.2.24–v1.2.34 sync" description="2026-03-26" tags={["New", "Updated", "Fixed"]}>
   Reviewed and triaged 43 automated Mintlify PRs (#86–#128). Merged 8, closed 30 (superseded or inaccurate), kept 5 pending v1.2.35 release. Validated all changes against upstream source code at v1.2.34.
 
   ## New sections
   - **Task scripts** (`concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`) — pre-execution bash scripts with `wakeAgent` JSON contract, `ScriptResult` type, execution flow
@@ -151,7 +164,7 @@
   - **CLAUDE.md template system** (`concepts/groups`, `api/group-management`) — automatic template copy during registration with `isMain`-based selection
   - **Channel-formatting skill** (`features/messaging`, `api/message-routing`, `integrations/slack`, `integrations/skills-system`) — per-channel text transformation table
   - **WhatsApp pairing code auth** (`integrations/whatsapp`) — tabbed QR code vs pairing code with phone number formatting rules
   - **loginctl linger** (`installation`, `quickstart`, `advanced/troubleshooting`) — systemd user service persistence after SSH logout
   - **Mount-allowlist preservation** (`quickstart`, `advanced/troubleshooting`) — `/setup` skips overwrite of existing config
 
   ## Updated
@@ -192,8 +205,8 @@
   - **Container runtime**: Container arguments code and key flags documented for both methods
   - **Architecture**: Startup sequence and container image updated
   - **Installation**: OneCLI added as prerequisite #5, `@onecli-sh/sdk` dependency
   - **Containers, Ollama, Skills examples**: Passing references updated to version-neutral language
   - **Customization**: Mount allowlist format updated (`allowedPaths` → `allowedRoots` with per-root read/write control)
   - **Product changelog**: Added v1.2.22 release entry and v1.2.0 scheduled task fix
 </Update>
 
@@ -215,7 +228,7 @@
 </Update>
 
 <Update label="PR consolidation and issue cleanup" description="2026-03-23" tags={["New", "Updated", "Fixed"]}>
   Reviewed, triaged, and consolidated 10 automated Mintlify PRs (#60–#69). Verified all changes against NanoClaw source code, excluded 6 incorrect changes, and resolved the final 2 open issues.
 
   ## New pages
   - **Claw CLI** (`features/cli`) — documents the `/claw` Python CLI for running agents from the command line (#64)
@@ -223,7 +236,7 @@
   ## New sections
   - **Apple Container vs Docker** (`advanced/container-runtime`) — when to use each runtime, key differences table, switching instructions (closes #50)
   - **Container internals** (`concepts/containers`) — allowed tools table, conversation archival, global memory injection, additional directory auto-discovery
   - **Slack message formatting** (`integrations/slack`) — mrkdwn syntax differences and `/slack-formatting` skill
   - **200-message history cap** (`features/messaging`) — documents the default query limit on message retrieval (closes #49)
   - **Opt-in diagnostics** (`concepts/security`, `quickstart`) — PostHog telemetry, consent flow, permanent opt-out (#68)
 
@@ -235,12 +248,12 @@
   - **Configuration** — fixed DATA_DIR description (runtime data, not legacy)
   - **Skills system** — added missing skills (`/get-qodo-rules`, `/qodo-pr-resolver`, `/x-integration`, `/add-compact`, `/add-parallel`, `/slack-formatting`)
   - **Contributing** — removed `/clear` from RFS (exists as `/add-compact`), updated to 4 skill types
   - **SEO descriptions** — improved frontmatter across 10 pages for better search discoverability
 
   ## Fixed
   - 13-page factual error sweep against source code (#67) — credential proxy terminology, IPC operations, container mount behavior, removed phantom MCP tool
   - Consolidated overlapping fixes from 6 PRs into 2 clean PRs (#70, #71), closing 7 automated PRs as superseded
   - Excluded incorrect automated changes: Channel Factory rename, fabricated commit reference, speculative formatting table, unverified frontmatter claims
 
   ## Housekeeping
   - Product changelog: added v1.2.20 (ESLint) and v1.2.21 (diagnostics) entries, fixed version ordering
@@ -252,21 +265,21 @@
   Ran a full docs-gap analysis against the upstream codebase and resolved 13 of 15 content-gap issues. Two low-priority items remain open (#49, #50).
 
   ## New pages
   - **Ollama integration** (`integrations/ollama`) — MCP server architecture, local model setup, third-party endpoints
   - **Voice transcription** (`features/voice-transcription`) — Whisper API (cloud) and whisper.cpp (local) with comparison table
   - **Image vision** (`features/image-vision`) — Multimodal image understanding for WhatsApp
   - **PDF reader** (`features/pdf-reader`) — Text extraction via poppler-utils
   - **X (Twitter) integration** (`integrations/x-twitter`) — Host+agent architecture, OAuth setup
   - **Parallel AI** (`integrations/parallel-ai`) — Web research MCP servers (quick search + deep research)
 
   ## Updated pages
   - **Skills system** — Documented channel fork architecture (5 fork repos), updated merge workflows, separated upstream vs fork skills
   - **Installation** — Added Windows (WSL) support across all sections: prerequisites, Docker Desktop WSL 2 backend, troubleshooting
   - **Security** — Documented sender allowlist: trigger/drop modes, per-chat overrides, file format
   - **Messaging** — Added `/compact` session command and authorization rules
   - **Telegram** — Expanded agent swarm section with installation and per-bot config
   - **WhatsApp** — Added skills summary table and emoji reactions section
   - **API reference** — Fixed `formatMessages` signature (added `timezone` param and `<context>` header)
   - **Configuration** — Added `OLLAMA_HOST`, expanded `ANTHROPIC_BASE_URL` and `SENDER_ALLOWLIST_PATH` docs
 
   ## Housekeeping
@@ -292,7 +305,7 @@
 
 <Update label="Source sync and remote control" description="2026-03-19" tags={["Updated"]}>
   - Fixed remote-control commands documentation
   - Deduplicated IPC docs
   - Added `update_task` to auth tables in API reference
 </Update>
 
@@ -308,12 +321,12 @@
 
 <Update label="v1.2.17 source sync" description="2026-03-18" tags={["New", "Updated"]}>
   - Documented `/capabilities` and `/status` container-agent skills as new pages
   - Synced docs with source code v1.2.17 — corrected mount allowlist format, interval drift handling, credential proxy behavior, and IPC config
   - Documented IPC task snapshot refresh and `update_task` operation
 </Update>
 
 <Update label="Credential proxy and task lifecycle" description="2026-03-16" tags={["Fixed"]}>
   Fixed stale documentation for credential proxy, database path, mount allowlist, and task lifecycle to match current source code.
 </Update>
 
 <Update label="Automation workflows" description="2026-03-16" tags={["New"]}>
@@ -324,7 +337,7 @@
 <Update label="Portal branding and UX" description="2026-03-16" tags={["Updated"]}>
   - Applied NanoClaw branding with custom theme colors, fonts, and SEO metadata
   - Switched theme from Aspen to Mint for better sidebar typography
   - Cleaned up introduction page, footer, and removed callout CSS override
 </Update>
 
 <Update label="Portal launch" description="2026-03-15" tags={["New"]}>

changelog/index.mdx

@@ -6,13 +6,24 @@
 tag: "UPDATED"
 ---
 
+<Update label="v2.0.48" description="2026-05-09" tags={["Feature"]}>
+  - Container config moved to the central DB — per-agent-group runtime config (provider, model, packages, MCP servers, mounts, skills) now lives in the `container_configs` table instead of `groups/<folder>/container.json`. Existing filesystem configs are backfilled automatically on startup. Managed via `ncl groups config get/update` and `config add-mcp-server/remove-mcp-server/add-package/remove-package`.
+  - Explicit restart with on-wake messages — config CLI operations no longer auto-kill containers. New `ncl groups restart` command with `--rebuild` and `--message` flags. On-wake messages (`on_wake` column on `messages_in`) are only picked up by a fresh container's first poll, preventing dying containers from stealing them during the SIGTERM grace period. Self-mod approval handlers (`install_packages`, `add_mcp_server`) use the same race-free mechanism.
+  - Per-group CLI scope — new `cli_scope` setting on container config (`disabled` / `group` / `global`, default `group`). Controls what the agent can access via `ncl` from inside the container. `disabled` excludes CLI instructions from `CLAUDE.md` and blocks all requests. `group` (default) restricts to own-group resources with auto-filled args. `global` gives unrestricted access (set automatically for owner agent groups). Includes post-handler result filtering to prevent cross-group data leaks and blocks `cli_scope` escalation from group-scoped agents.
+</Update>
+
+<Update label="v2.0.45" description="2026-05-08" tags={["Feature"]}>
+  - Admin CLI (`ncl`) — new `ncl` command for querying and modifying the central DB: agent groups, messaging groups, wirings, users, roles, members, destinations, sessions, approvals, and dropped messages. Host-side transport via Unix socket; container-side transport via session DB. Write operations from inside containers go through the approval flow. `list` supports column filtering and `--limit`. Run `ncl help` for usage.
+  - v1 → v2 migration — run `bash migrate-v2.sh` from the v2 checkout. Finds your v1 install, merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders, copies session data with conversation continuity, ports scheduled tasks, interactively selects and installs channels, copies container skills, builds the agent container, and offers a service switchover. Hands off to Claude (`/migrate-from-v1`) for owner seeding, access policy, and CLAUDE.md cleanup.
+</Update>
+
 <Update label="v2.0.0" description="2026-04-22" tags={["Breaking"]}>
   - Ground-up architectural rewrite with new entity model (users, roles, messaging groups, agent groups, wirings)
   - Two-database session model — `inbound.db` (host writes) and `outbound.db` (container writes) eliminate cross-mount SQLite contention
   - Agent-runner moved from Node.js to Bun — runs TypeScript directly without compilation
   - Shared-source agent-runner — `/app/src` is a read-only bind mount, source changes never require image rebuild
   - `tini` as PID 1 for proper signal forwarding
   - Three-level channel isolation model with `unknown_sender_policy` (strict, request_approval, public)
   - Per-wiring engage modes: `pattern`, `mention`, `mention-sticky`
   - Sender scope enforcement per wiring (`all` or `known`)
   - Channel and sender approval flows with interactive cards
@@ -38,20 +49,20 @@
 
 <Update label="v1.2.51" description="2026-04-05" tags={["Fix"]}>
   - Fixed writable global memory mount for main agent — corrected the path in container `CLAUDE.md`
   - Fixed three issues in the Karpathy wiki skill
   - Updated `init-onecli` skill to use `ONECLI_URL` variable
 </Update>
 
 <Update label="v1.2.50" description="2026-04-05" tags={["Feature", "Skill"]}>
   - Lowered auto-compact threshold to 165k tokens for better context fidelity
   - Added `/add-karpathy-llm-wiki` skill — persistent wiki knowledge base per group, based on Karpathy's LLM Wiki pattern
   - Added `/migrate-nanoclaw` skill — intent-based upgrade that extracts customizations into a migration guide and reapplies them on a clean upstream base
   - Added `/migrate-from-openclaw` skill — guided migration from OpenClaw installations
   - NanoClaw now suggests `/migrate-nanoclaw` when the user's fork is far behind upstream
 </Update>
 
 <Update label="v1.2.49" description="2026-04-04" tags={["Feature"]}>
   - Added automatic session artifact pruning on startup and daily — cleans up stale session JSONLs (7 days), debug logs (3 days), todo files (3 days), and telemetry (7 days) while preserving active sessions
 </Update>
 
 <Update label="v1.2.48" description="2026-04-04" tags={["Feature"]}>
@@ -66,7 +77,7 @@
 <Update label="v1.2.46" description="2026-04-03" tags={["Feature", "Channel"]}>
   - Added reply/quoted message context support — channels can now pass `reply_to_message_id`, `reply_to_message_content`, and `reply_to_sender_name` fields with messages
   - Reply context is rendered as `<quoted_message>` XML in agent prompts, giving agents full awareness of which message a user is responding to
   - Database migration adds reply context columns to the messages table (nullable for backward compatibility)
 </Update>
 
 <Update label="v1.2.45" description="2026-04-02" tags={["Skill", "Maintenance"]}>
@@ -76,7 +87,7 @@
 
 <Update label="v1.2.43" description="2026-03-29" tags={["Fix"]}>
   - Auto-recover from stale Claude Code session IDs instead of retrying infinitely — detects missing session transcripts and clears the broken session for a fresh retry
   - Removed built-in Ollama MCP server from core — Ollama integration is now exclusively available via the `/add-ollama-tool` skill
   - Fixed npm audit dependency errors
 </Update>
 
@@ -86,7 +97,7 @@
 </Update>
 
 <Update label="v1.2.41" description="2026-03-28" tags={["Fix", "Maintenance"]}>
   - Migrated `x-integration` host.ts from pino to built-in logger (follow-up to v1.2.36 cleanup)
   - Fixed `stopContainer()` test compatibility — mocked container-runtime so tests don't require Docker
   - Cleared stale Telegram token from `.env.example`
 </Update>
@@ -96,7 +107,7 @@
 </Update>
 
 <Update label="v1.2.39" description="2026-03-27" tags={["Fix", "Security"]}>
   - Security fixes: command injection prevention in `stopContainer` (name validation), mount path colon rejection, allowlist caching fix (contributed by @foxsky)
 </Update>
 
 <Update label="v1.2.38" description="2026-03-27" tags={["Fix"]}>
@@ -110,7 +121,7 @@
 <Update label="v1.2.36" description="2026-03-27" tags={["Maintenance", "Fix", "Breaking"]}>
   - **[BREAKING]** Replaced `pino` logger with built-in logger module — removes 2 runtime dependencies. WhatsApp users must re-merge the WhatsApp fork to pick up the Baileys logger compatibility fix: `git fetch whatsapp main && git merge whatsapp/main`. If the `whatsapp` remote is not configured: `git remote add whatsapp https://github.com/qwibitai/nanoclaw-whatsapp.git`
   - Removed `yaml` and `zod` dependencies — core runtime now uses only 3 packages
   - Updated Ollama skill with admin model management tools
   - Channel-formatting text-style fixes for WhatsApp and Telegram (contributed by @kenbolton)
 </Update>
 
@@ -133,7 +144,7 @@
 <Update label="v1.2.32" description="2026-03-25" tags={["Feature", "Skill", "Fix"]}>
   - Added `/channel-formatting` skill — channel-aware text formatting for WhatsApp, Telegram, Slack, and Signal
   - Fixed per-group trigger pattern matching — each group can now define its own trigger word (contributed by @mrbob-git)
   - Fixed `loginctl enable-linger` so systemd user service survives SSH logout (contributed by @IYENTeam)
   - Clarified WhatsApp phone number prompt to prevent auth failures (contributed by @ingyukoh)
   - Added Telegram forum topics contributor (contributed by @flobo3)
 </Update>
@@ -162,7 +173,7 @@
 </Update>
 
 <Update label="v1.2.26" description="2026-03-25" tags={["Fix"]}>
   - Enabled `loginctl linger` during setup so systemd user service survives SSH logout
   - Clarified WhatsApp phone number prompt format (digits only, no `+` prefix)
   - Added CLAUDE.md template copy during IPC group registration
 </Update>
@@ -181,7 +192,7 @@
   - Added `/use-native-credential-proxy` skill — opt-in restoration of the built-in `.env`-based credential proxy for users who prefer it over OneCLI
   - Removed dead `src/credential-proxy.ts` code (unused since v1.2.22)
   - Updated token count to 39.8k tokens (20% of context window)
   - Upgraded Zod dependency from v3 to v4 (`^4.3.6`)
 </Update>
 
 <Update label="v1.2.22" description="2026-03-24" tags={["Maintenance"]}>
@@ -229,7 +240,7 @@
 </Update>
 
 <Update label="v1.2.13" description="2026-03-14" tags={["Feature", "Breaking"]}>
   Major architecture change: skills are now git branches, channels are separate fork repos.
 
   ## Features
   - Skills live as `skill/*` git branches merged via `git merge` — no more marketplace or plugin system
@@ -299,7 +310,7 @@
 </Update>
 
 <Update label="v1.2.3" description="2026-03-04" tags={["Feature", "Security"]}>
   - Added sender allowlist for per-chat access control to restrict who can interact with the agent
 </Update>
 
 <Update label="v1.2.2" description="2026-03-04" tags={["Feature", "Fix"]}>
@@ -316,13 +327,13 @@
 </Update>
 
 <Update label="v1.2.0" description="2026-03-02" tags={["Feature", "Breaking", "Channel"]}>
   Major release introducing multi-channel architecture. WhatsApp is no longer hardcoded — all channels self-register via a channel registry.
 
   ## Features
   - **Channel registry**: Channels self-register at module load time via `registerChannel()` factory pattern
   - **`isMain` flag**: Explicit boolean replaces folder-name-based main group detection
   - **Channel-prefixed group folders**: Groups use `whatsapp_main`, `telegram_family-chat` convention to prevent cross-channel collisions
   - Unconfigured channels now emit WARN logs naming the exact missing variable
 
   ## Breaking
   - **WhatsApp moved to skill**: No longer part of core — apply with `/add-whatsapp`
@@ -363,7 +374,7 @@
 
   ## Fixes
   - Fixed WhatsApp QR data handling
   - Rebased core skills (Telegram, Discord, voice) to latest main
 </Update>
 
 <Update label="v1.1.2" description="2026-02-24" tags={["Fix"]}>
@@ -372,7 +383,7 @@
 
 <Update label="v1.1.1" description="2026-02-24" tags={["Feature", "Fix"]}>
   ## Features
   - Added official Qodo skills and codebase intelligence
   - Rewrote README for broader audience
 
   ## Fixes

concepts/containers.mdx

@@ -4,7 +4,7 @@
 tag: "UPDATED"
 ---
 
 NanoClaw runs all agents inside containers (lightweight Linux VMs) to provide true OS-level isolation. This is the primary security boundary that makes Bash access and code execution safe.
 
 ## Why containers?
 
@@ -34,7 +34,7 @@
 - **Tools**: `agent-browser` for browser automation, `vercel` CLI, `curl`, `git`
 - **SDK**: `@anthropic-ai/claude-code` installed globally via pnpm
 - **PID 1**: `tini` for proper signal forwarding so `outbound.db` writes finalize on SIGTERM
 - **User**: `node` (uid 1000, non-root)
 - **Working directory**: `/workspace/group`
 
 <Note>
@@ -45,7 +45,7 @@
 
 The entrypoint uses `tini` for signal forwarding:
 
 1. **tini** starts as PID 1 (forwards signals cleanly)
 2. **entrypoint.sh** runs setup scripts
 3. **Bun executes agent-runner**: `exec bun run /app/src/index.ts`
 4. Agent-runner polls `inbound.db` for messages and writes responses to `outbound.db`
@@ -74,23 +74,23 @@
 |-------|---------------|------|---------|
 | Session folder | `/workspace` | Read-write | `inbound.db`, `outbound.db`, `outbox/`, `.claude/` |
 | Agent group folder | `/workspace/agent` | Read-write | Working files, `CLAUDE.local.md` |
-| Container config | `/workspace/agent/container.json` | Read-only | Nested RO mount (agent can't modify config) |
+| Container config | `/workspace/agent/container.json` | Read-only | Materialized snapshot of the DB row at spawn time |
 | Composed CLAUDE.md | `/workspace/agent/CLAUDE.md` | Read-only | Regenerated each spawn |
 | CLAUDE.md fragments | `/workspace/agent/.claude-fragments` | Read-only | Fragment files for composition |
 | Global memory | `/workspace/global` | Read-only | `groups/global/` directory |
 | Shared CLAUDE.md | `/app/CLAUDE.md` | Read-only | Base CLAUDE.md |
 | Agent-runner source | `/app/src` | Read-only | Shared source (bind mount from host) |
 | Container skills | `/app/skills` | Read-only | Shared skill definitions |
 | Claude SDK state | `/home/node/.claude` | Read-write | SDK state + skill symlinks |
-| Additional mounts | `/workspace/extra/{name}` | Per-config | From `container.json` (validated against allowlist) |
+| Additional mounts | `/workspace/extra/{name}` | Per-config | From the agent group's container config (validated against allowlist) |
 
-<Warning>
-The `container.json` file is mounted read-only as a nested mount inside the read-write agent group folder. This prevents the agent from modifying its own container configuration.
-</Warning>
+<Note>
+Per-agent-group container config (provider, model, packages, MCP servers, mounts, skills, `cli_scope`) lives in the `container_configs` table in the central DB. The `container.json` mount is materialized from the DB row at spawn time so the container runner sees a stable snapshot. Existing `groups/<folder>/container.json` files are backfilled into the DB automatically on startup.
+</Note>
 
 ### Mount security
 
 All additional mounts are validated against the allowlist at `~/.config/nanoclaw/mount-allowlist.json`:
 
 ```json
 {
@@ -101,7 +101,7 @@
       "description": "Development projects"
     }
   ],
   "blockedPatterns": ["password", "secret", "token"]
 }
 ```
 
@@ -143,18 +143,38 @@
 - **Stale detection**: host sweep detects containers with old heartbeats or stuck processing_ack
 - **Fallback**: SIGKILL if graceful stop fails
 
+### Explicit restart and on-wake messages
+
+Use `ncl groups restart --id <group-id> [--rebuild] [--message <text>]` to restart all running containers in an agent group. Config CLI operations no longer auto-kill containers — restart is always explicit.
+
+- `--rebuild` rebuilds the per-agent-group image first
+- `--message` writes an on-wake message that the fresh container picks up on its first poll
+- Without `--message`, containers come back on the next user message
+- From inside a container, `--id` is auto-filled and only the calling session is restarted
+
+On-wake messages are race-free: the `on_wake` flag on `messages_in` ensures the message is only delivered to a fresh container's first poll iteration. A dying container in its SIGTERM grace period can never steal it. The same mechanism is used by the self-mod approval handlers (`install_packages`, `add_mcp_server`).
+
 <Info>
 Even if the container crashes, all data in session databases and mounted directories persists. Only the container process itself is ephemeral.
 </Info>
 
 ## Per-agent-group images
 
-Agent groups can specify custom packages in `container.json`. The host builds a derived Docker image with additional apt and npm packages:
+Agent groups can specify custom apt and npm packages on their container config row. The host builds a derived Docker image with the additional packages:
 
 - Image tag: derived from the checkout-scoped base image and agent group
 - Built on top of the base `nanoclaw-agent-v2-<slug>:latest` image
 - Cached — only rebuilt when package lists change
 
+Manage packages via the admin CLI:
+
+```bash
+ncl groups config add-package --id <group-id> --type apt --name jq
+ncl groups config remove-package --id <group-id> --type npm --name some-pkg
+```
+
+Package CLI operations no longer auto-kill containers. Use `ncl groups restart --id <group-id> --rebuild` to apply package changes to running containers.
+
 ## Timeouts
 
 ### Container timeout
@@ -187,7 +207,12 @@
 - `schedule_task`, `cancel_task`, `pause_task`, `resume_task`, `update_task` — task management
 - `list_tasks` — view scheduled tasks
 
-Additional MCP servers can be configured in `container.json`.
+Additional MCP servers are stored on the agent group's container config row and managed via the admin CLI:
+
+```bash
+ncl groups config add-mcp-server --id <group-id> --name my-server --command /path/to/server
+ncl groups config remove-mcp-server --id <group-id> --name my-server
+```
 
 ### Global memory injection
 
@@ -206,7 +231,7 @@
 - **Headless**: always (no display in container)
 - **User data**: stored in group folder (persists across runs)
 - **Network**: full access (same as host, no restrictions)
 - **Optional CJK fonts**: install via `INSTALL_CJK_FONTS=true` build arg (~200 MB)
 
 ## Security implications
 
@@ -219,13 +244,13 @@
 
 ### What containers DON'T protect against
 
 - **Network access** — agents have full network access (can exfiltrate data)
 - **Mounted directory tampering** — agents can modify anything in mounted read-write directories
 - **Vault-based API access** — containers can make authenticated API requests through the OneCLI vault (though they cannot extract real credentials)
 - **Resource exhaustion** — no CPU/memory limits enforced (can DoS host)
 
 <Warning>
 Containers provide filesystem isolation, not network isolation. Agents can make arbitrary HTTP requests and exfiltrate data over the network.
 </Warning>
 
 ## Troubleshooting
@@ -246,7 +271,7 @@
 
 1. Check mount paths are readable by host user
 2. Check uid/gid mapping
 3. Verify allowlist includes path (for additional mounts)
 4. Check symlink resolution didn't change path
 
 ## Related topics

concepts/groups.mdx

@@ -4,7 +4,7 @@
 tag: "UPDATED"
 ---
 
 In v2, NanoClaw uses a new entity model that separates **agent groups** (workspaces where agents run) from **messaging groups** (platform chats and channels). These are connected through **wirings** — many-to-many relationships that control how messages are routed to agents.
 
 ## Entity model
 
@@ -14,7 +14,7 @@
 
 - A workspace with its own folder under `groups/{name}/`
 - An optional provider configuration
-- A container configuration (`container.json`) with custom packages and mounts
+- A container configuration row in the `container_configs` table (custom packages, MCP servers, mounts, `cli_scope`)
 - The unit of credential scoping (each gets its own OneCLI agent)
 
 ### Messaging groups
@@ -26,9 +26,9 @@
 - Can be denied (sets `denied_at` to silently drop future mentions)
 - Auto-created on first mention or DM
 
 ### Wirings (messaging_group_agents)
 
 Wirings connect messaging groups to agent groups with four orthogonal axes:
 
 | Axis | Options | Purpose |
 |------|---------|---------|
@@ -92,7 +92,7 @@
 
 Three critical invariants ensure correctness across Docker mount boundaries:
 
 1. **`journal_mode=DELETE`** — WAL's mmapped `-shm` file doesn't refresh host-to-guest
 2. **Host opens-writes-closes per operation** — closing invalidates the container's page cache
 3. **One writer per file** — DELETE-mode journal unlink isn't atomic across the mount
 
@@ -100,9 +100,9 @@
 
 ### User model
 
 Users are identified by namespaced platform identifiers:
 
 - `phone:+15551234567` (WhatsApp, iMessage)
 - `tg:123456789` (Telegram)
 - `discord:123456789` (Discord)
 - `email:user@example.com` (Gmail)
@@ -121,10 +121,10 @@
 
 ## Channel approval
 
 When a message arrives on an unwired channel (no agent wirings exist), the channel-request gate escalates to the owner:
 
 1. Owner receives an approval card
 2. **Approve** — creates a wiring with defaults (`mention-sticky` for groups, `pattern='.'` for DMs), admits the triggering sender, replays the original event
 3. **Deny** — sets `denied_at` on the messaging group; future mentions drop silently
 
 ## Global memory
@@ -137,17 +137,13 @@
 
 ## Additional mounts
 
-Agent groups can have extra directories mounted via `container.json`:
+Agent groups can request extra host directories on their container config row (`additional_mounts`). Each entry has the shape:
 
 ```json
 {
-  "additionalMounts": [
-    {
-      "hostPath": "/Users/you/projects/website",
-      "containerPath": "website",
-      "readonly": true
-    }
-  ]
+  "hostPath": "/Users/you/projects/website",
+  "containerPath": "website",
+  "readonly": true
 }
 ```
 
@@ -164,12 +160,30 @@
 Additional mounts bypass group isolation. Only mount directories that are safe for the agent to access.
 </Warning>
 
+## CLI scope
+
+Each agent group has a `cli_scope` setting on its container config that controls what the agent can access via `ncl` from inside the container:
+
+| Value | Behavior |
+|-------|----------|
+| `disabled` | Agent never learns about `ncl` — CLI instructions are excluded from `CLAUDE.md` and the host rejects every request |
+| `group` (default) | Agent can only access its own group's resources (`groups`, `sessions`, `destinations`, `members`). `--id` and group-scoped args are auto-filled. Cross-group access is rejected. |
+| `global` | Unrestricted access. Set automatically for owner agent groups via `init-first-agent`. |
+
+Group-scoped agents cannot escalate their own scope — `cli_scope` updates are blocked on requests originating inside a group-scoped container. Post-handler result filtering also prevents cross-group data from leaking through `list`/`get` responses.
+
+Update via:
+
+```bash
+ncl groups config update --id <group-id> --cli-scope global
+```
+
 ## Concurrency
 
 Container concurrency is managed globally:
 
 - **Max concurrent containers**: 5 by default (`MAX_CONCURRENT_CONTAINERS`)
 - **Wake deduplication**: concurrent wake calls for the same session share a single in-flight promise
 - **Delivery polls**: active poll (1s) for running containers, sweep poll (60s) for all sessions
 
 ## Best practices

features/customization.mdx

@@ -10,7 +10,7 @@
 1. **Code changes** — for behavior baked into the orchestrator (trigger pattern, polling, timeouts)
 2. **Wiring settings** — per-messaging-group config stored in the central DB (engage mode, sender scope, session mode)
 3. **Skills** — for features and integrations (install via `/add-<name>`, uninstall via `git revert`)
 4. **Mount allowlist** — for which host directories an agent can see
 
 ## Philosophy
 
@@ -99,7 +99,7 @@
 MAX_CONCURRENT_CONTAINERS=10 systemctl --user restart nanoclaw
 ```
 
 Or persist in your systemd / launchd service definition.
 
 ## Per-wiring behavior (engage mode, sender scope, session mode)
 
@@ -150,9 +150,9 @@
 
 `CLAUDE.md` is composed at session start — a shared base plus the per-group fragment. Per-group changes don't affect other agent groups.
 
 ## Mount allowlist
 
 Agents only see what you mount. The allowlist lives at `~/.config/nanoclaw/mount-allowlist.json` (outside the project root, never mounted into containers):
 
 ```json
 {
@@ -168,12 +168,12 @@
       "description": "Development project"
     }
   ],
   "blockedPatterns": [],
   "nonMainReadOnly": true
 }
 ```
 
-Per-agent-group mount requests live in `groups/<folder>/container.json`. The host validates each request against the allowlist before mounting. See [Security model](/advanced/security-model) for the full picture.
+Per-agent-group mount requests live in the `container_configs` table (`additional_mounts` column) and are managed via `ncl groups config update`. The host validates each request against the allowlist before mounting. See [Security model](/advanced/security-model) for the full picture.
 
 ## The `/customize` skill
 
@@ -235,6 +235,6 @@
 ## Related
 
 - [Messaging](/features/messaging) — inbound routing and engage evaluation
 - [Scheduled tasks](/features/scheduled-tasks) — task model and cron
 - [Security](/concepts/security) — sender policies, user roles
 - [Architecture](/concepts/architecture) — two-DB session model