Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 24 additions & 3 deletions advanced/container-runtime.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@
| Health check | `docker info` | `container system status` |
| Platform | macOS, Linux, Windows (WSL2) | macOS 15+ only |

### Switching runtimes

Check warning on line 48 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L48

Did you really mean 'runtimes'?

Run the `/convert-to-apple-container` skill in Claude Code. To revert, use `git revert`.

Expand All @@ -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)

Check warning on line 60 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L60

Did you really mean 'tini'?
- **pnpm** (via corepack) — for global Node CLI installs

Check warning on line 61 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L61

Did you really mean 'corepack'?
- **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`

Check warning on line 68 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L68

Did you really mean 'allowlist'?
- **Runs as `node` user** (non-root) with `/workspace/group` as working directory
- **Entrypoint**: `tini -> entrypoint.sh -> exec bun run /app/src/index.ts`

Expand All @@ -77,7 +77,7 @@

### 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 via their container config (managed with `ncl groups config add-package/remove-package`). 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`
Expand All @@ -94,7 +94,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) |

Check warning on line 97 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L97

Did you really mean 'channel_type'?

Check warning on line 97 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L97

Did you really mean 'platform_id'?

Check warning on line 97 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L97

Did you really mean 'thread_id'?

### outbound.db (container writes, host reads)

Expand All @@ -109,7 +109,7 @@

Three invariants are critical for correctness:

1. **`journal_mode=DELETE`** — WAL's mmapped `-shm` doesn't refresh across Docker mounts

Check warning on line 112 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L112

Did you really mean 'WAL's'?

Check warning on line 112 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L112

Did you really mean 'mmapped'?
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

Expand All @@ -117,11 +117,11 @@

### Spawning containers

Containers are spawned by the `spawnContainer` function. Wake calls are deduplicated via an in-flight promise map.

Check warning on line 120 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L120

Did you really mean 'deduplicated'?

<Steps>
<Step title="Read agent group config">
The host reads `container.json` and resolves provider contributions.
The host reads the `container_configs` row for the agent group, materializes it to `groups/<folder>/container.json`, and resolves provider contributions.
</Step>

<Step title="Build volume mounts">
Expand Down Expand Up @@ -151,13 +151,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 the `container_configs` table 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 |

Check warning on line 160 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L160

Did you really mean 'allowlist'?
| Provider mounts | Various | Per-provider | Provider-contributed |

### Timeouts and stale detection
Expand All @@ -165,13 +165,34 @@
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

Check warning on line 168 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L168

Did you really mean 'mtime'?

### Container shutdown

- `killContainer(sessionId, reason)` stops the container via `docker stop`, falls back to SIGKILL
- An optional `onExit` callback fires after the process exits, guaranteeing the old container is gone before any respawn happens

Check warning on line 173 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L173

Did you really mean 'respawn'?
- On close/error, the session is marked stopped and typing indicators are cleared

### Explicit restart with on-wake messages

Config CLI operations no longer auto-kill containers. To restart an agent group's container, use:

```bash
ncl groups restart --id <group-id> [--rebuild] [--message <text>]
```

When `--message` is provided, the host writes the wake message to `messages_in` with the `on_wake` flag set, kills the running container, and respawns via the `onExit` callback. The `on_wake` flag ensures the message is picked up only by the fresh container's first poll iteration — a dying container in its SIGTERM grace period can never steal it.

Check warning on line 184 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L184

Did you really mean 'respawns'?

Self-mod approval handlers (`install_packages`, `add_mcp_server`) use the same race-free mechanism: rebuild the image when needed, write an `on_wake` message, kill the container, and respawn via `onExit`.

Check warning on line 186 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L186

Did you really mean 'respawn'?

### CLI scope enforcement

The agent group's `cli_scope` setting (`disabled`, `group`, `global`) controls what the in-container agent can do via `ncl`. Enforcement is host-side, applied in the dispatcher:

- `disabled` rejects every `cli_request` and excludes the `ncl` instructions from the composed CLAUDE.md
- `group` (default) restricts requests to `groups`, `sessions`, `destinations`, and `members` for the agent group itself, auto-fills `--id` and group args, rejects cross-group access, blocks `cli_scope` mutations, and runs post-handler result filtering to prevent cross-group data leaks in list responses
- `global` (set automatically for owner agent groups) is unrestricted

## Credential injection

The OneCLI SDK's `applyContainerConfig()` configures each container's network to route through the vault:
Expand Down Expand Up @@ -204,7 +225,7 @@

<Accordion title="Inspect container mounts">
```bash
docker inspect nanoclaw-{session-id} | jq '.[0].Mounts'

Check warning on line 228 in advanced/container-runtime.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

advanced/container-runtime.mdx#L228

Did you really mean 'jq'?
```
</Accordion>

Expand Down
31 changes: 30 additions & 1 deletion api/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 container runtime config (provider, model, packages, MCP servers, mounts, skills, `cli_scope`) lives in the `container_configs` table in the central DB. The host materializes it to `groups/<folder>/container.json` at spawn time. Manage with `ncl groups config get/update`.

## Environment variables

Configuration is read from `.env` file or `process.env`, with hardcoded fallbacks.

Check warning on line 11 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L11

Did you really mean 'hardcoded'?

<ParamField path="ASSISTANT_NAME" type="string" default="Andy">
Name of the assistant. Used in trigger pattern and message routing.
Expand Down Expand Up @@ -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.

Check warning on line 58 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L58

Did you really mean 'cron'?
</ParamField>

## Timezone configuration
Expand All @@ -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.

Check warning on line 70 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L70

Did you really mean 'cron'?

## Directory paths

Expand All @@ -90,9 +90,38 @@
</ResponseField>

<ResponseField name="MOUNT_ALLOWLIST_PATH" type="string">
`~/.config/nanoclaw/mount-allowlist.json` — mount security allowlist (never mounted into containers)

Check warning on line 93 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L93

Did you really mean 'allowlist'?
</ResponseField>

## Per-agent-group container config

Stored in the `container_configs` table in the central DB; one row per agent group. Materialized to `groups/<folder>/container.json` at spawn time. Edit only via `ncl` — do not modify `container.json` directly.

Common fields:

| Field | Description |
|-------|-------------|
| `provider`, `model` | Agent provider and model selection |
| `packages.apt`, `packages.npm` | Extra apt and npm packages to bake into the per-group image |
| `mcp_servers` | Additional MCP servers wired to the container |
| `additional_mounts` | Extra host directories (validated against the mount allowlist) |

Check warning on line 107 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L107

Did you really mean 'allowlist'?
| `skills` | Container skill list |
| `cli_scope` | `disabled` / `group` (default) / `global` — controls in-container `ncl` access |

Manage container config:

```bash
ncl groups config get --id <group-id>
ncl groups config update --id <group-id> --model <model>
ncl groups config add-mcp-server --id <group-id> ...
ncl groups config remove-mcp-server --id <group-id> ...
ncl groups config add-package --id <group-id> --type apt --name <pkg>
ncl groups config remove-package --id <group-id> --type npm --name <pkg>
ncl groups restart --id <group-id> [--rebuild] [--message <text>]
```

Existing filesystem `container.json` files are backfilled into the DB automatically on first startup after upgrading.

Check warning on line 123 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L123

Did you really mean 'backfilled'?

## Trigger pattern

The default trigger pattern is generated from `ASSISTANT_NAME`:
Expand Down Expand Up @@ -135,5 +164,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

Check warning on line 167 in api/configuration.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/configuration.mdx#L167

Did you really mean 'allowlist'?
- The `.env` file is read by the config module for NanoClaw settings only (not for API keys)
2 changes: 1 addition & 1 deletion api/group-management.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: Group management
description: API reference for agent groups, messaging groups, wirings, and the v2 entity model

Check warning on line 3 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L3

Did you really mean 'wirings'?
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`.

Check warning on line 7 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L7

Did you really mean 'wirings'?

## Entity model

Expand All @@ -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; the host materializes it to `groups/<folder>/container.json` at spawn time. Manage with `ncl groups config get/update`.
- Each gets its own OneCLI agent identifier for credential scoping

### Messaging groups
Expand All @@ -45,9 +45,9 @@
- Auto-created on first mention or DM
- `denied_at` silently drops future mentions

### Wirings (messaging_group_agents)

Check warning on line 48 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L48

Did you really mean 'Wirings'?

Check warning on line 48 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L48

Did you really mean 'messaging_group_agents'?

Wirings connect messaging groups to agent groups:

Check warning on line 50 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L50

Did you really mean 'Wirings'?

```typescript
interface MessagingGroupAgent {
Expand Down Expand Up @@ -129,8 +129,8 @@
|-------|---------|
| `agent_groups` | Agent workspaces |
| `messaging_groups` | Platform chats/channels |
| `messaging_group_agents` | Wirings with engage/scope/session config |

Check warning on line 132 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L132

Did you really mean 'Wirings'?
| `users` | Namespaced platform identifiers |

Check warning on line 133 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L133

Did you really mean 'Namespaced'?
| `user_roles` | Owner and admin roles |
| `agent_group_members` | Unprivileged membership |
| `user_dms` | Cached DM channel mapping |
Expand Down Expand Up @@ -162,13 +162,13 @@

## Channel approval flow

When a message arrives on an unwired channel:

Check warning on line 165 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L165

Did you really mean 'unwired'?

1. Router detects no wirings exist for this messaging group

Check warning on line 167 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L167

Did you really mean 'wirings'?
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)

Check warning on line 171 in api/group-management.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

api/group-management.mdx#L171

Did you really mean 'DMs'?
- Triggering sender is auto-admitted as a member
- Original event is replayed
4. **Deny** — sets `denied_at` on the messaging group
Expand Down
12 changes: 12 additions & 0 deletions changelog/docs-updates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,20 +5,32 @@
rss: true
---

<Update label="v2.0.48 sync: container config in DB, on-wake messages, CLI scope" description="2026-05-09" tags={["Updated"]}>
Documented the v2.0.45 → v2.0.48 changes: per-agent-group container runtime config moved from `groups/<folder>/container.json` files to the `container_configs` central-DB table (filesystem configs backfilled on startup, materialized to `container.json` at spawn time), explicit container restart via `ncl groups restart` with race-free `on_wake` messages, and per-group `cli_scope` (`disabled` / `group` / `global`).

Check warning on line 9 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L9

Did you really mean 'configs'?

Check warning on line 9 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L9

Did you really mean 'backfilled'?

## Updated
- **`concepts/containers.mdx`**: container config table sourced from the DB; new "Explicit restart" subsection covering `ncl groups restart`, the `on_wake` flag, and the `onExit` callback contract; new "CLI scope" subsection.
- **`concepts/groups.mdx`**: agent group definition now references `container_configs`; additional-mounts wording aligned with DB-stored config.
- **`advanced/container-runtime.mdx`**: spawn flow reads from `container_configs` and materializes `container.json`; mounts table updated; added "Explicit restart with on-wake messages" and "CLI scope enforcement" subsections.
- **`api/configuration.mdx`**: new "Per-agent-group container config" section listing common fields and `ncl groups config` verbs, including `cli_scope`.
- **`api/group-management.mdx`**: corrected the claim that container config lives on disk only — now in the DB, materialized at spawn time.
- **`changelog/index.mdx`**: added `v2.0.48` and `v2.0.45` 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.

Check warning on line 26 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L26

Did you really mean 'launchd'?

Check warning on line 26 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L26

Did you really mean 'systemd'?
- **`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.

Check warning on line 27 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L27

Did you really mean 'reframed'?

Check warning on line 27 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L27

Did you really mean 'iMessage'?

Check warning on line 27 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L27

Did you really mean 'Webex'?
- **`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`)

Check warning on line 33 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L33

Did you really mean 'Ollama'?

## Token count sync
- `integrations/skills-system.mdx`: 43.8k → 127k
Expand All @@ -26,15 +38,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.

Check warning on line 41 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L41

Did you really mean 'api'?

## 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`

Check warning on line 45 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L45

Did you really mean 'wirings'?
- **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`

Check warning on line 49 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L49

Did you really mean 'cron'?
- **OneCLI Agent Vault** is the sole credential path; legacy credential proxy removed — `advanced/security-model`, `api/configuration`
- **Changelog**: v2.0.0 release entry

Expand All @@ -59,14 +71,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"]}>

Check warning on line 74 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L74

Did you really mean 'requiresTrigger'?
Triaged 3 automated Mintlify PRs (#175–#177). Merged #177 (most comprehensive), closed #175 and #176 (superseded). Cherry-picked unique content from closed PRs.

Check warning on line 75 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L75

Did you really mean 'Triaged'?

## Updated
- **Store mount (rw)**: Documented `store/` read-write mount for main agent across containers, container-runtime, security, security-model, groups, customization pages

Check warning on line 78 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L78

Did you really mean 'rw'?
- **`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

Check warning on line 81 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L81

Did you really mean 'register_group'?
- **`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
Expand All @@ -87,11 +99,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).

Check warning on line 102 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L102

Did you really mean 'triaged'?

## 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

Check warning on line 106 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L106

Did you really mean 'Ollama'?

Check warning on line 106 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L106

Did you really mean 'Ollama'?
- **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
Expand All @@ -104,23 +116,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

Check warning on line 119 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L119

Did you really mean 'param'?
- **`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.

Check warning on line 126 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L126

Did you really mean 'Gavriel'?
</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.

Check warning on line 130 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L130

Did you really mean 'triaged'?

## 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).

Check warning on line 133 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L133

Did you really mean 'rebrand'?
- **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`

Check warning on line 135 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L135

Did you really mean 'deps'?
- **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
Expand All @@ -130,9 +142,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

Check warning on line 145 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L145

Did you really mean 'kubelet'?
- **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

Check warning on line 147 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L147

Did you really mean 'allowlist'?
- **Configuration**: Added `MAX_MESSAGES_PER_PROMPT` and `LOG_LEVEL` environment variables
- **Skills**: Added `/init-onecli` (operational) and `/add-emacs` (upstream)

Expand All @@ -143,7 +155,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.

Check warning on line 158 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L158

Did you really mean 'triaged'?

## New sections
- **Task scripts** (`concepts/tasks`, `features/scheduled-tasks`, `api/task-scheduling`) — pre-execution bash scripts with `wakeAgent` JSON contract, `ScriptResult` type, execution flow
Expand All @@ -151,7 +163,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

Check warning on line 166 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L166

Did you really mean 'loginctl'?

Check warning on line 166 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L166

Did you really mean 'systemd'?
- **Mount-allowlist preservation** (`quickstart`, `advanced/troubleshooting`) — `/setup` skips overwrite of existing config

## Updated
Expand Down Expand Up @@ -192,8 +204,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

Check warning on line 207 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L207

Did you really mean 'Ollama'?
- **Customization**: Mount allowlist format updated (`allowedPaths` → `allowedRoots` with per-root read/write control)

Check warning on line 208 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L208

Did you really mean 'allowlist'?
- **Product changelog**: Added v1.2.22 release entry and v1.2.0 scheduled task fix
</Update>

Expand All @@ -215,7 +227,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.

Check warning on line 230 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L230

Did you really mean 'triaged'?

## New pages
- **Claw CLI** (`features/cli`) — documents the `/claw` Python CLI for running agents from the command line (#64)
Expand All @@ -223,7 +235,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

Check warning on line 238 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L238

Did you really mean 'mrkdwn'?
- **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)

Expand All @@ -235,12 +247,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

Check warning on line 250 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L250

Did you really mean 'frontmatter'?

Check warning on line 250 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L250

Did you really mean '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

Check warning on line 255 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L255

Did you really mean 'frontmatter'?

## Housekeeping
- Product changelog: added v1.2.20 (ESLint) and v1.2.21 (diagnostics) entries, fixed version ordering
Expand All @@ -252,21 +264,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

Check warning on line 267 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L267

Did you really mean 'Ollama'?
- **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

Check warning on line 269 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L269

Did you really mean 'Multimodal'?
- **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

Check warning on line 275 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L275

Did you really mean 'repos'?
- **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

Check warning on line 277 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L277

Did you really mean 'allowlist'?
- **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)

Check warning on line 281 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L281

Did you really mean 'param'?
- **Configuration** — Added `OLLAMA_HOST`, expanded `ANTHROPIC_BASE_URL` and `SENDER_ALLOWLIST_PATH` docs

## Housekeeping
Expand All @@ -292,7 +304,7 @@

<Update label="Source sync and remote control" description="2026-03-19" tags={["Updated"]}>
- Fixed remote-control commands documentation
- Deduplicated IPC docs

Check warning on line 307 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L307

Did you really mean 'Deduplicated'?
- Added `update_task` to auth tables in API reference
</Update>

Expand All @@ -308,12 +320,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

Check warning on line 323 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L323

Did you really mean 'allowlist'?
- 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.

Check warning on line 328 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L328

Did you really mean 'allowlist'?
</Update>

<Update label="Automation workflows" description="2026-03-16" tags={["New"]}>
Expand All @@ -324,7 +336,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

Check warning on line 339 in changelog/docs-updates.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/docs-updates.mdx#L339

Did you really mean 'callout'?
</Update>

<Update label="Portal launch" description="2026-03-15" tags={["New"]}>
Expand Down
11 changes: 11 additions & 0 deletions changelog/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,24 @@
tag: "UPDATED"
---

<Update label="v2.0.48" description="2026-05-09" tags={["Feature"]}>
- **Container config moved to DB.** Per-agent-group container 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`.

Check warning on line 10 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L10

Did you really mean 'configs'?

Check warning on line 10 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L10

Did you really mean 'backfilled'?
- **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.

Check warning on line 16 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L16

Did you really mean 'wirings'?
- **v1 → v2 migration.** Run `bash migrate-v2.sh` from the v2 checkout. Finds your v1 install (sibling directory or `NANOCLAW_V1_PATH`), merges `.env`, seeds the v2 DB from `registered_groups`, copies group folders (`CLAUDE.md` → `CLAUDE.local.md`), 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 to test. Hands off to Claude (`/migrate-from-v1`) for owner seeding, access policy, CLAUDE.md cleanup, and fork customization porting.
</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)

Check warning on line 21 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L21

Did you really mean '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)

Check warning on line 26 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L26

Did you really mean 'request_approval'?
- Per-wiring engage modes: `pattern`, `mention`, `mention-sticky`
- Sender scope enforcement per wiring (`all` or `known`)
- Channel and sender approval flows with interactive cards
Expand All @@ -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

Check warning on line 52 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L52

Did you really mean 'Karpathy'?
- 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

Check warning on line 58 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L58

Did you really mean 'Karpathy's'?
- 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

Check warning on line 65 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L65

Did you really mean 'JSONLs'?
</Update>

<Update label="v1.2.48" description="2026-04-04" tags={["Feature"]}>
Expand All @@ -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)

Check warning on line 80 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L80

Did you really mean 'nullable'?
</Update>

<Update label="v1.2.45" description="2026-04-02" tags={["Skill", "Maintenance"]}>
Expand All @@ -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

Check warning on line 90 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L90

Did you really mean 'Ollama'?

Check warning on line 90 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L90

Did you really mean 'Ollama'?
- Fixed npm audit dependency errors
</Update>

Expand All @@ -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)

Check warning on line 100 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L100

Did you really mean 'pino'?
- Fixed `stopContainer()` test compatibility — mocked container-runtime so tests don't require Docker
- Cleared stale Telegram token from `.env.example`
</Update>
Expand All @@ -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)

Check warning on line 110 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L110

Did you really mean 'allowlist'?
</Update>

<Update label="v1.2.38" description="2026-03-27" tags={["Fix"]}>
Expand All @@ -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

Check warning on line 124 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L124

Did you really mean 'Ollama'?
- Channel-formatting text-style fixes for WhatsApp and Telegram (contributed by @kenbolton)
</Update>

Expand All @@ -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)

Check warning on line 147 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L147

Did you really mean 'systemd'?
- Clarified WhatsApp phone number prompt to prevent auth failures (contributed by @ingyukoh)
- Added Telegram forum topics contributor (contributed by @flobo3)
</Update>
Expand Down Expand Up @@ -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

Check warning on line 176 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L176

Did you really mean 'systemd'?
- Clarified WhatsApp phone number prompt format (digits only, no `+` prefix)
- Added CLAUDE.md template copy during IPC group registration
</Update>
Expand All @@ -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`)

Check warning on line 195 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L195

Did you really mean 'Zod'?
</Update>

<Update label="v1.2.22" description="2026-03-24" tags={["Maintenance"]}>
Expand Down Expand Up @@ -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.

Check warning on line 243 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L243

Did you really mean 'repos'?

## Features
- Skills live as `skill/*` git branches merged via `git merge` — no more marketplace or plugin system
Expand Down Expand Up @@ -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

Check warning on line 313 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L313

Did you really mean 'allowlist'?
</Update>

<Update label="v1.2.2" description="2026-03-04" tags={["Feature", "Fix"]}>
Expand All @@ -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.

Check warning on line 330 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L330

Did you really mean 'hardcoded'?

## 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

Check warning on line 336 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L336

Did you really mean 'Unconfigured'?

## Breaking
- **WhatsApp moved to skill**: No longer part of core — apply with `/add-whatsapp`
Expand Down Expand Up @@ -363,7 +374,7 @@

## Fixes
- Fixed WhatsApp QR data handling
- Rebased core skills (Telegram, Discord, voice) to latest main

Check warning on line 377 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L377

Did you really mean 'Rebased'?
</Update>

<Update label="v1.1.2" description="2026-02-24" tags={["Fix"]}>
Expand All @@ -372,7 +383,7 @@

<Update label="v1.1.1" description="2026-02-24" tags={["Feature", "Fix"]}>
## Features
- Added official Qodo skills and codebase intelligence

Check warning on line 386 in changelog/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

changelog/index.mdx#L386

Did you really mean 'Qodo'?
- Rewrote README for broader audience

## Fixes
Expand Down
32 changes: 25 additions & 7 deletions concepts/containers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Check warning on line 7 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L7

Did you really mean 'VMs'?

## Why containers?

Expand Down Expand Up @@ -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)

Check warning on line 37 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L37

Did you really mean 'uid'?
- **Working directory**: `/workspace/group`

<Note>
Expand All @@ -45,7 +45,7 @@

The entrypoint uses `tini` for signal forwarding:

1. **tini** starts as PID 1 (forwards signals cleanly)

Check warning on line 48 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L48

Did you really mean 'tini'?
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`
Expand Down Expand Up @@ -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 the `container_configs` DB table 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 container config (validated against allowlist) |

Check warning on line 85 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L85

Did you really mean '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>
**Container config in the DB (v2.0.48+).** Per-agent-group container runtime config (provider, model, packages, MCP servers, mounts, skills, `cli_scope`) lives in the `container_configs` table in the central DB. The host materializes it to `groups/<folder>/container.json` at spawn time so the container runner can read it, and mounts that file read-only into the container. Existing filesystem configs are backfilled into the DB automatically on startup. Manage with `ncl groups config get/update`.

Check warning on line 88 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L88

Did you really mean 'configs'?

Check warning on line 88 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L88

Did you really mean 'backfilled'?
</Note>

### Mount security

All additional mounts are validated against the allowlist at `~/.config/nanoclaw/mount-allowlist.json`:

Check warning on line 93 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L93

Did you really mean 'allowlist'?

```json
{
Expand All @@ -101,7 +101,7 @@
"description": "Development projects"
}
],
"blockedPatterns": ["password", "secret", "token"]

Check warning on line 104 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L104

Did you really mean 'blockedPatterns'?
}
```

Expand Down Expand Up @@ -143,13 +143,19 @@
- **Stale detection**: host sweep detects containers with old heartbeats or stuck processing_ack
- **Fallback**: SIGKILL if graceful stop fails

### Explicit restart

Config changes do not auto-kill containers. Use `ncl groups restart --id <group-id>` (with optional `--rebuild` to rebuild the image, or `--message <text>` to deliver a wake message after the new container starts). The host writes the on-wake message to `messages_in` with the `on_wake` flag set, kills the running container, and respawns via an `onExit` callback so the old container is fully gone before the new one starts.

The `on_wake` flag ensures wake messages are picked up only by a fresh container's first poll iteration. This prevents the race where a dying container in its SIGTERM grace period could steal the message. Self-mod approval handlers (`install_packages`, `add_mcp_server`) use the same race-free mechanism.

<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 packages in their container config (use `ncl groups config add-package/remove-package`). 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
Expand Down Expand Up @@ -187,7 +193,19 @@
- `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/remove-mcp-server`.

### CLI scope

Each agent group's container config has a `cli_scope` setting that controls what the agent can do with `ncl` from inside the container:

| Value | Behavior |
|-------|----------|
| `disabled` | Agent never sees `ncl` instructions in CLAUDE.md, and the host rejects every `cli_request` from the container. |
| `group` (default) | Agent can access `groups`, `sessions`, `destinations`, `members` only, scoped to its own agent group. `--id` and group args are auto-filled, cross-group access is rejected, and `cli_scope` changes are blocked. Post-handler result filtering prevents cross-group data leaks. |
| `global` | Unrestricted. Set automatically for owner agent groups. |

This setting is only modifiable from outside the container (host-side `ncl` over the Unix socket) — group-scoped agents cannot escalate themselves.

### Global memory injection

Expand All @@ -206,7 +224,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)

Check warning on line 227 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L227

Did you really mean 'arg'?

## Security implications

Expand All @@ -219,13 +237,13 @@

### What containers DON'T protect against

- **Network access** — agents have full network access (can exfiltrate data)

Check warning on line 240 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L240

Did you really mean 'exfiltrate'?
- **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.

Check warning on line 246 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L246

Did you really mean 'exfiltrate'?
</Warning>

## Troubleshooting
Expand All @@ -246,7 +264,7 @@

1. Check mount paths are readable by host user
2. Check uid/gid mapping
3. Verify allowlist includes path (for additional mounts)

Check warning on line 267 in concepts/containers.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/containers.mdx#L267

Did you really mean 'allowlist'?
4. Check symlink resolution didn't change path

## Related topics
Expand Down
4 changes: 2 additions & 2 deletions concepts/groups.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Check warning on line 7 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L7

Did you really mean 'wirings'?

## Entity model

Expand All @@ -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 in the `container_configs` table — provider, model, packages, MCP servers, mounts, skills, and `cli_scope`. The host materializes it to `groups/<folder>/container.json` at spawn time. Manage via `ncl groups config get/update`.
- The unit of credential scoping (each gets its own OneCLI agent)

### Messaging groups
Expand All @@ -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)

Check warning on line 29 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L29

Did you really mean 'Wirings'?

Check warning on line 29 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L29

Did you really mean 'messaging_group_agents'?

Wirings connect messaging groups to agent groups with four orthogonal axes:

Check warning on line 31 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L31

Did you really mean 'Wirings'?

| Axis | Options | Purpose |
|------|---------|---------|
Expand Down Expand Up @@ -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

Check warning on line 95 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L95

Did you really mean 'WAL's'?

Check warning on line 95 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L95

Did you really mean 'mmapped'?
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

Expand All @@ -100,9 +100,9 @@

### User model

Users are identified by namespaced platform identifiers:

Check warning on line 103 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L103

Did you really mean 'namespaced'?

- `phone:+15551234567` (WhatsApp, iMessage)

Check warning on line 105 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L105

Did you really mean 'iMessage'?
- `tg:123456789` (Telegram)
- `discord:123456789` (Discord)
- `email:user@example.com` (Gmail)
Expand All @@ -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:

Check warning on line 124 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L124

Did you really mean 'unwired'?

Check warning on line 124 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L124

Did you really mean 'wirings'?

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

Check warning on line 127 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L127

Did you really mean 'DMs'?
3. **Deny** — sets `denied_at` on the messaging group; future mentions drop silently

## Global memory
Expand All @@ -137,7 +137,7 @@

## Additional mounts

Agent groups can have extra directories mounted via `container.json`:
Agent groups can have extra directories mounted via the container config (stored in the `container_configs` table, materialized to `container.json` at spawn time):

```json
{
Expand Down Expand Up @@ -169,7 +169,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

Check warning on line 172 in concepts/groups.mdx

View check run for this annotation

Mintlify / Mintlify Validation (qwibitai-nanoclaw-8) - vale-spellcheck

concepts/groups.mdx#L172

Did you really mean 'deduplication'?
- **Delivery polls**: active poll (1s) for running containers, sweep poll (60s) for all sessions

## Best practices
Expand Down