Move container config to DB-backed storage

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,11 +77,90 @@
 
 ### Per-agent-group images
 
-Agent groups can specify custom packages in `container.json`. The host builds a derived Docker image:
+Agent groups can specify custom packages in their container config (stored in the `container_configs` DB table). 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
+- Resulting image tag is written back to the `container_configs.image_tag` column
+
+## Container configuration storage
+
+Per-agent-group runtime config lives in the `container_configs` table in the central DB. The legacy `groups/<folder>/container.json` file is now a **materialized view** — written by the host at spawn time, read by the container at startup. The container has no idea the DB exists; nothing inside the container changed.
+
+### Schema
+
+The `container_configs` table has one row per agent group, with both scalar and JSON columns:
+
+| Column | Type | Purpose |
+|---|---|---|
+| `agent_group_id` | TEXT (PK, FK) | References `agent_groups.id` (cascades on delete) |
+| `provider` | TEXT | Agent provider override (`claude`, `opencode`, etc.) |
+| `model` | TEXT | Model name (e.g., `claude-sonnet-4-6`) |
+| `effort` | TEXT | Reasoning effort hint |
+| `image_tag` | TEXT | Persisted Docker image tag for per-group builds |
+| `assistant_name` | TEXT | Display name in system prompt |
+| `max_messages_per_prompt` | INTEGER | Override for `MAX_MESSAGES_PER_PROMPT` |
+| `skills` | TEXT (JSON) | `"all"` or `["skill1", ...]` |
+| `mcp_servers` | TEXT (JSON) | `Record<string, McpServerConfig>` |
+| `packages_apt` | TEXT (JSON) | `string[]` of apt packages |
+| `packages_npm` | TEXT (JSON) | `string[]` of npm packages |
+| `additional_mounts` | TEXT (JSON) | `AdditionalMountConfig[]` |
+| `cli_scope` | TEXT | `disabled` \| `group` (default) \| `global` — controls in-container `ncl` access |
+| `updated_at` | TEXT | ISO timestamp |
+
+### Backfill
+
+On startup, the host runs a one-time backfill that seeds `container_configs` rows from any existing `groups/<folder>/container.json` files (and the legacy `agent_groups.agent_provider` column). The backfill is idempotent — it skips groups that already have a row.
+
+### Provider cascade
+
+Provider resolution simplified from a 3-step cascade to 2 steps:
+
+```
+sessions.agent_provider
+  → container_configs.provider
+  → 'claude'
+```
+
+The legacy `agent_groups.agent_provider` column is retained for backwards compat but no longer participates in resolution and is no longer exposed via `ncl groups`. Configure provider via `ncl groups config update --id <group-id> --provider <name>`.
+
+### Updating config
+
+All writes go through the DB layer. Multi-word verbs accept either spaces (preferred) or dashes — `ncl groups config get` and `ncl groups config-get` both work.
+
+- **`ncl groups config update`** — change scalar fields (`--provider`, `--model`, `--effort`, `--image-tag`, `--assistant-name`, `--max-messages-per-prompt`, `--cli-scope`)
+- **`ncl groups config add-mcp-server`** / **`config remove-mcp-server`** — manage MCP servers
+- **`ncl groups config add-package`** / **`config remove-package`** — manage apt/npm packages
+- **Self-mod approvals** (`install_packages`, `add_mcp_server`) — write to DB instead of file
+- **`ncl groups config get`** — view current config (open access; others require approval)
+
+Config CLI ops only write to the DB; restart is now a separate command — see "Explicit restart" below. The host helper `restartAgentGroupContainers()` is invoked by self-mod approvals to apply config changes.
+
+### CLI scope
+
+`cli_scope` controls what an in-container agent can do via `ncl`:
+
+| Value | Behavior |
+|---|---|
+| `disabled` | Agent never learns about `ncl` (the instructions section is excluded from the composed `CLAUDE.md`). The host CLI dispatcher rejects any `cli_request`. |
+| `group` (default) | Agent can call `groups`, `sessions`, `destinations`, `members` only, scoped to its own agent group. `--id`, `--agent_group_id`, and `--group` args are auto-filled. Cross-group reads are rejected post-handler; help output reflects the scope. `cli_scope` arg is blocked outright. |
+| `global` | Unrestricted — current behavior. Set automatically for owner agent groups by `init-first-agent`. |
+
+Enforcement is host-side only — no image rebuild or env var needed.
+
+### Explicit restart
+
+```bash
+ncl groups restart --id <group-id> [--rebuild] [--message <text>]
+```
+
+- Kills running containers for the agent group; without `--message`, they come back on the next inbound message
+- With `--message`, an `on_wake` row is written to `inbound.db` and the container respawns immediately via the `onExit` callback
+- `--rebuild` forces an image rebuild before respawn (useful after package changes); package commands no longer trigger a build implicitly
+- Called from inside a container, `--id` is auto-filled and only the calling session is restarted
+
+The `on_wake` flag on `messages_in` ensures wake messages are delivered only on the new container's first poll iteration. Without it, the dying container — still in its SIGTERM grace window — could steal the message before exiting. `killContainer` accepts an `onExit` callback that fires after the process actually exits, guaranteeing race-free respawn.
 
 ## Two-database IO model
 
@@ -94,7 +173,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 +188,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 +196,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.
+  <Step title="Materialize container config">
+    The host reads the agent group's row from the `container_configs` DB table and writes it as `groups/<folder>/container.json`. This file is a materialized view — the DB is the source of truth, and the file is regenerated on every spawn so the runner always sees fresh config. Provider contributions are resolved from this config.
   </Step>
 
   <Step title="Build volume mounts">
@@ -151,13 +230,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 from DB at spawn time |
 | 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,7 +244,7 @@
 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
 
@@ -204,7 +283,7 @@
 
 <Accordion title="Inspect container mounts">
   ```bash
   docker inspect nanoclaw-{session-id} | jq '.[0].Mounts'
   ```
 </Accordion>
 

advanced/troubleshooting.mdx

@@ -133,21 +133,24 @@
 
 ### Solutions
 
-<Accordion title="Increase timeout for specific group">
-  Modify the group's `containerConfig` in the database:
-  
+<Accordion title="Inspect or change a group's container config">
+  Container config lives in the `container_configs` table in `data/v2.db`. Inspect with the CLI:
+
   ```bash
-  sqlite3 store/messages.db
+  ncl groups config get --id <agent-group-id>
   ```
-
-  ```sql
-  UPDATE registered_groups 
-  SET container_config = json_set(
-    COALESCE(container_config, '{}'),
-    '$.timeout',
-    3600000  -- 1 hour in milliseconds
-  )
-  WHERE name = 'Family Chat';
+
+  Update scalar fields (e.g., model, effort, image tag, max messages per prompt). Config writes only touch the DB — to apply the change to a running container, follow up with `ncl groups restart`:
+
+  ```bash
+  ncl groups config update --id <agent-group-id> --model claude-sonnet-4-6 --max-messages-per-prompt 20
+  ncl groups restart --id <agent-group-id>
+  ```
+
+  Or query directly with SQLite:
+
+  ```bash
+  sqlite3 data/v2.db "SELECT * FROM container_configs WHERE agent_group_id = '<id>';"
   ```
 </Accordion>
 
@@ -189,7 +192,7 @@
 
 ### Cause
 
 By default, systemd sets `Linger=no` for users. When your last SSH session closes, systemd terminates all user-level processes — including the NanoClaw service. This is especially common on cloud VMs (EC2, GCP, Oracle Cloud).
 
 ### Solution
 
@@ -207,7 +210,7 @@
 ```
 
 <Note>
   If `loginctl enable-linger` fails with a permission error, your system may require polkit authorization. Contact your system administrator or run the command with `sudo`.
 </Note>
 
 ## Known issues
@@ -233,7 +236,7 @@
 
 **Symptoms:** `Container exited with code 125: pull access denied for nanoclaw-agent` — the container image disappears after a few hours, even though you just built it.
 
 **Cause:** If your container runtime has Kubernetes enabled (Rancher Desktop enables it by default), the kubelet runs image garbage collection when disk usage exceeds 85%. NanoClaw containers are ephemeral (run and exit), so `nanoclaw-agent:latest` is never protected by a running container. The kubelet sees it as unused and deletes it — often overnight when no messages are being processed.
 
 **Fix:** Disable Kubernetes if you don't need it:
 
@@ -256,7 +259,7 @@
 grep -E "image found|image NOT found|image missing" logs/nanoclaw.log
 ```
 
 If you need Kubernetes enabled, set `CONTAINER_IMAGE` to an image stored in a registry that the kubelet won't garbage-collect, or raise the kubelet's GC thresholds.
 
 ### Resume branches from stale tree position
 
@@ -304,7 +307,7 @@
 
 <CodeGroup>
 ```bash macOS
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw
 ```
 
 ```bash Linux
@@ -346,7 +349,7 @@
 
 <CodeGroup>
 ```bash macOS
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw
 ```
 
 ```bash Linux
@@ -370,8 +373,8 @@
 # Verify the mount allowlist is readable
 cat ~/.config/nanoclaw/mount-allowlist.json
 
-# Check group's container_config in DB
-sqlite3 store/messages.db "SELECT name, container_config FROM registered_groups;"
+# Check a group's container config (mounts and packages live here)
+sqlite3 data/v2.db "SELECT agent_group_id, additional_mounts, packages_apt, packages_npm FROM container_configs;"
 ```
 
 ### Solutions
@@ -393,21 +396,21 @@
   }
   ```
 
   Then restart the service. If the mount allowlist file did not exist at startup, NanoClaw will detect it once created without requiring a restart.
 </Accordion>
 
 <Accordion title="Reset mount allowlist to defaults">
   If you need to regenerate the default mount allowlist (for example, after a misconfiguration), re-run setup with the `--force` flag:
 
   ```bash
   claude /setup --force
   ```
 
   Without `--force`, setup skips the mount allowlist if it already exists to preserve your customizations.
 </Accordion>
 
 <Accordion title="Check for symlinks">
   The mount security system resolves symlinks before validation. If you're mounting a symlink, ensure the resolved path is in the allowlist:
 
   ```bash
   readlink -f /path/to/symlink
@@ -415,7 +418,7 @@
 </Accordion>
 
 <Accordion title="Verify file permissions">
   Containers run as the host user (or uid 1000 on some systems). Ensure the host user can read the mounted directories:
 
   ```bash
   ls -la /path/to/mount
@@ -493,7 +496,7 @@
 
 | Artifact | Retention | Notes |
 |----------|-----------|-------|
 | Session JSONLs and tool results | 7 days | Active sessions (from DB) are never deleted |
 | Debug logs | 3 days | Active sessions skipped |
 | Todo files | 3 days | Active sessions skipped |
 | Telemetry | 7 days | Active sessions skipped |
@@ -509,7 +512,7 @@
 
 ## Stale session auto-recovery
 
 NanoClaw automatically detects and recovers from stale or corrupt sessions. When a container fails because the session transcript file (`.jsonl`) is missing — due to a crash mid-write, manual deletion, or disk-full condition — NanoClaw clears the broken session ID and lets the existing backoff mechanism in the group queue retry with a fresh session.
 
 Stale sessions are detected by matching the error output against known patterns (`no conversation found`, `ENOENT` on `.jsonl` files, or `session not found`). Only these specific signals trigger session clearing — transient errors (network, API) fall through to the normal retry path.
 

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 configuration (provider, model, packages, MCP servers, mounts) lives in the `container_configs` table in the central DB and is materialized to `groups/<folder>/container.json` at spawn time. See [Container runtime](/advanced/container-runtime#container-configuration-storage) for details.
 
 ## 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
 
@@ -17,14 +17,16 @@
   id: string;             // Unique identifier
   name: string;           // Display name
   folder: string;         // Filesystem folder name
-  agent_provider?: string; // Optional provider override
+  /** @deprecated Use container_configs.provider instead. */
+  agent_provider: string | null;
   created_at: string;     // ISO timestamp
 }
 ```
 
 - 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` DB table (one row per agent group); the file `groups/<folder>/container.json` is materialized at spawn time
 - Each gets its own OneCLI agent identifier for credential scoping
+- `agent_provider` is deprecated and no longer exposed via the CLI — use `ncl groups config update --provider` to set the provider on the `container_configs` row instead
 
 ### Messaging groups
 
@@ -45,9 +47,40 @@
 - Auto-created on first mention or DM
 - `denied_at` silently drops future mentions
 
+### Container configs
+
+Per-agent-group runtime config:
+
+```typescript
+interface ContainerConfigRow {
+  agent_group_id: string;            // PK and FK to agent_groups.id
+  provider: string | null;           // 'claude', 'opencode', etc.
+  model: string | null;              // Model name (e.g., 'claude-sonnet-4-6')
+  effort: string | null;             // Reasoning effort hint
+  image_tag: string | null;          // Persisted Docker image tag
+  assistant_name: string | null;     // Display name in system prompt
+  max_messages_per_prompt: number | null;
+  skills: string;                    // JSON: '"all"' | '["skill1","skill2"]'
+  mcp_servers: string;               // JSON: Record<string, McpServerConfig>
+  packages_apt: string;              // JSON: string[]
+  packages_npm: string;              // JSON: string[]
+  additional_mounts: string;         // JSON: AdditionalMountConfig[]
+  cli_scope: string;                 // 'disabled' | 'group' | 'global' (default 'group')
+  updated_at: string;
+}
+```
+
+Source of truth in the DB. Materialized to `groups/<folder>/container.json` at spawn time so the in-container runner can read it from the read-only mount. All writes go through `ncl groups config <verb>` operations or self-mod approvals — see [Container runtime](/advanced/container-runtime#container-configuration-storage) for the full list.
+
+`cli_scope` controls what the in-container agent can do via `ncl`:
+
+- **`disabled`** — agent never learns about `ncl` (instructions excluded from `CLAUDE.md`); host dispatch rejects any `cli_request`
+- **`group`** (default) — agent can call `groups`, `sessions`, `destinations`, `members` only, scoped to its own agent group; `--id` and group args are auto-filled and cross-group reads are rejected; `cli_scope` changes are blocked
+- **`global`** — unrestricted; set automatically on the owner's first agent group via `init-first-agent`
+
 ### Wirings (messaging_group_agents)
 
 Wirings connect messaging groups to agent groups:
 
 ```typescript
 interface MessagingGroupAgent {
@@ -128,9 +161,10 @@
 | Table | Purpose |
 |-------|---------|
 | `agent_groups` | Agent workspaces |
+| `container_configs` | Per-agent-group runtime config (provider, model, packages, MCP servers, mounts) |
 | `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 |
@@ -162,13 +196,13 @@
 
 ## 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

concepts/architecture.mdx

@@ -5,7 +5,7 @@
 keywords: ["architecture", "system design", "single process"]
 ---
 
 NanoClaw is a lightweight AI assistant that runs agents in isolated containers. The v2 architecture is a ground-up rewrite built on a two-database session model, a pluggable module system, and a new entity model that separates users, agent groups, messaging groups, and wirings.
 
 ## High-level overview
 
@@ -41,7 +41,7 @@
 
 ### Channel adapters
 
 NanoClaw uses a self-registering adapter pattern for messaging channels. Installed adapters such as Telegram, Discord, WhatsApp, Signal, Slack, Teams, iMessage, and the local CLI register at startup. Channels with missing credentials are skipped with a warning.
 
 All adapters implement a common interface with `onInbound`, `onInboundEvent`, `onMetadata`, and `onAction` callbacks, allowing the rest of the system to be channel-agnostic.
 
@@ -49,16 +49,16 @@
 
 The router (`src/router.ts`) is the central message routing pipeline:
 
 1. **Thread policy** — non-threaded adapters (Telegram, WhatsApp, iMessage) collapse `threadId` to null
 2. **Messaging group lookup** — finds or auto-creates messaging groups on mentions/DMs
 3. **Unwired channel handling** — if no agents are wired, the channel-request gate escalates to the owner for approval
 4. **Sender resolution** — the permissions module extracts namespaced user IDs and upserts users
 5. **Fan-out** — each wired agent is evaluated independently against engage mode, sender scope, and access gates
 6. **Engage evaluation** — per-agent decision based on `pattern`, `mention`, or `mention-sticky` mode
 7. **Delivery** — engaging agents get a session wake and container spawn; non-engaging agents with `accumulate` policy store the message for future context
 
 <Info>
 Message IDs are namespaced by agent group ID to prevent collisions during fan-out to multiple agents.
 </Info>
 
 ### Session manager
@@ -77,7 +77,7 @@
 
 The container runner (`src/container-runner.ts`) spawns and manages isolated agent execution:
 
 - **Wake deduplication** — concurrent wake calls for the same session are deduplicated via an in-flight promise map
 - **Per-agent-group images** — custom Docker images with additional apt/npm packages can be built per agent group
 - **Shared source** — `/app/src` is a read-only bind mount from the host; source changes never require an image rebuild
 - **No stdin/stdout** — all IO is via the two-DB split; no stdin piping or output markers
@@ -92,7 +92,7 @@
 - **Retry** — 3 attempts per message, then permanently failed
 
 <Note>
 Deduplication via an in-flight set prevents double-delivery when both polls hit the same session simultaneously.
 </Note>
 
 ### Host sweep
@@ -100,7 +100,7 @@
 The host sweep (`src/host-sweep.ts`) runs every 60 seconds:
 
 - Syncs `processing_ack` from `outbound.db` to update inbound message status
 - Detects stale containers via heartbeat mtime and processing_ack age
 - Wakes containers for due messages (scheduled tasks with `process_after <= now`)
 - Advances recurring task series (creates next-occurrence rows)
 
@@ -108,26 +108,27 @@
 
 **Central database** (`data/v2.db`) stores the entity model:
 
-- **agent_groups** — workspaces with folder, name, and optional provider
+- **agent_groups** — workspaces with folder and name (provider moved to `container_configs.provider`)
+- **container_configs** — per-agent-group runtime config (provider, model, effort, packages, MCP servers, additional mounts); materialized to `groups/<folder>/container.json` at spawn time
 - **messaging_groups** — platform chats with `unknown_sender_policy` (`strict`, `request_approval`, or `public`)
 - **messaging_group_agents** — many-to-many wirings with engage mode, pattern, sender scope, ignored message policy, session mode, and priority
 - **users** — namespaced platform identifiers (e.g., `phone:+1555...`, `tg:123`, `discord:456`)
 - **user_roles** — owner (always global) or admin (global or scoped to agent group)
 - **sessions** — status tracking for both session and container
 
 **Session inbound.db** (host writes, container reads):
 
 - **messages_in** — inbound messages with status, `process_after`, recurrence, `series_id`, and trigger flag
 - **delivered** — tracks delivery outcomes
 - **destinations** — live destination map (channels and other agents)
 - **session_routing** — default reply routing
 
 **Session outbound.db** (container writes, host reads):
 
 - **messages_out** — outbound messages with `deliver_after` and recurrence
 - **processing_ack** — tracks which inbound messages the container has processed
 - **session_state** — persistent key/value store (e.g., SDK session ID for resume)
 - **container_state** — tool-in-flight state for stuck-detection
 
 ### Module system
 
@@ -231,7 +232,7 @@
 - **Tools**: `agent-browser`, `vercel` CLI, `curl`, `git`
 - **SDK**: `@anthropic-ai/claude-code` (Claude Agent SDK)
 - **PID 1**: `tini` for proper signal forwarding
 - **User**: Runs as `node` user (uid 1000, non-root)
 - **Working directory**: `/workspace/group`
 
 <Info>
@@ -240,12 +241,12 @@
 
 ## Startup sequence
 
 1. **Central DB initialization** — opens `data/v2.db`, runs migrations, performs one-time filesystem cutover
 2. **Container runtime check** — ensures Docker is running, cleans up orphan containers
 3. **Channel adapter initialization** — registers all channel adapters with `onInbound`, `onInboundEvent`, `onMetadata`, and `onAction` callbacks
 4. **Delivery adapter bridge** — bridges the delivery system to channel adapters for `deliver()` and `setTyping()` calls
 5. **Delivery polls** — starts active poll (1s for running containers) and sweep poll (60s for all active sessions)
 6. **Host sweep** — 60s sweep for processing_ack sync, stale detection, due-message wake, and recurrence advancement
 
 ## Graceful shutdown
 

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 from DB at spawn time (agent can't modify) |
 | 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 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.
+The `container.json` file is a **materialized view** of the DB-backed `container_configs` row. The host writes it at spawn time and mounts it read-only as a nested mount inside the read-write agent group folder. The agent cannot modify its own container configuration — config changes go through self-mod approvals or `ncl groups config <verb>` commands.
 </Warning>
 
 ### 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"]
 }
 ```
 
@@ -142,18 +142,31 @@
 - **Host-initiated**: `docker stop` sends SIGTERM; `tini` forwards to Bun process
 - **Stale detection**: host sweep detects containers with old heartbeats or stuck processing_ack
 - **Fallback**: SIGKILL if graceful stop fails
+- **`onExit` callback**: `killContainer` accepts an optional callback that fires after the process actually exits, used by the restart flow to guarantee the old container is gone before the new one spawns
 
 <Info>
 Even if the container crashes, all data in session databases and mounted directories persists. Only the container process itself is ephemeral.
 </Info>
 
+### Explicit restart
+
+`ncl groups restart --id <group-id> [--rebuild] [--message <text>]` kills running containers for the agent group and lets them respawn:
+
+- Without `--message`, containers come back on the next inbound message
+- With `--message`, an `on_wake` message is queued in `inbound.db` and the container respawns immediately via the `onExit` callback
+- `--rebuild` forces an image rebuild before respawn (useful after package changes)
+- Called from inside a container, `--id` is auto-filled and only the calling session is restarted
+
+The `on_wake` flag on `messages_in` ensures wake messages are delivered only on the fresh container's first poll iteration. This prevents the dying container — still in its SIGTERM grace window — from stealing the message before it exits.
+
 ## 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 packages in their container config (the `container_configs` DB table — materialized to `container.json` at spawn time). The host builds a derived Docker image with additional apt and npm 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
+- Image tag is persisted to the DB after build
 
 ## Timeouts
 
@@ -187,7 +200,7 @@
 - `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 can be configured per-agent-group via `ncl groups config add-mcp-server` (writes to the `container_configs` DB table).
 
 ### Global memory injection
 
@@ -206,7 +219,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 +232,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 +259,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
 
@@ -13,8 +13,7 @@
 An agent group is:
 
 - A workspace with its own folder under `groups/{name}/`
-- An optional provider configuration
-- A container configuration (`container.json`) with custom packages and mounts
+- A row in the `container_configs` DB table with provider, model, effort, packages, MCP servers, and additional mounts
 - The unit of credential scoping (each gets its own OneCLI agent)
 
 ### Messaging groups
@@ -26,9 +25,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 +91,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 +99,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 +120,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,7 +136,7 @@
 
 ## Additional mounts
 
-Agent groups can have extra directories mounted via `container.json`:
+Agent groups can have extra directories mounted via the `additional_mounts` JSON column on their `container_configs` row. The materialized `container.json` mounted into the container looks like this:
 
 ```json
 {
@@ -169,7 +168,7 @@
 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 `additional_mounts` JSON column on the `container_configs` row, materialized to `groups/<folder>/container.json` at spawn time. 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