Document per-group model and effort overrides

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, some configuration has moved to per-agent-group `container.json` (materialized from the `container_configs` table at spawn time).
 
 ## 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,9 +90,30 @@
 </ResponseField>
 
 <ResponseField name="MOUNT_ALLOWLIST_PATH" type="string">
   `~/.config/nanoclaw/mount-allowlist.json` — mount security allowlist (never mounted into containers)
 </ResponseField>
 
+## Per-agent-group container config
+
+Each agent group has its own entry in the `container_configs` table that controls how its container is spawned. The host materializes this row into `groups/<folder>/container.json` at spawn time so the container runner can read it.
+
+Recognized fields include:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `provider` | string | Agent provider (`claude`, `opencode`, etc.). Defaults to `claude`. |
+| `model` | string | Model alias (`sonnet`, `opus`, `haiku`) or full model ID. Passed through to the provider SDK. If omitted, the SDK default is used. |
+| `effort` | string | Reasoning effort: `low`, `medium`, `high`, `xhigh`, or `max`. Passed through to the provider SDK. If omitted, the SDK default is used. |
+| `assistantName` | string | Display name used in trigger and routing. |
+| `maxMessagesPerPrompt` | number | Per-prompt message cap (default `10`). |
+| `mcpServers` | object | Additional MCP servers exposed to the agent. |
+| `packages` | object | Extra `apt` and `npm` packages to install when building the per-group image. |
+| `additionalMounts` | array | Extra host directories to mount (validated against the allowlist). |
+| `skills` | array \| `"all"` | Container skills to expose. |
+| `imageTag` | string | Override the derived per-group image tag. |
+
+Per-group `model` and `effort` overrides let different workspaces target different models or reasoning budgets without changing host environment variables.
+
 ## Trigger pattern
 
 The default trigger pattern is generated from `ASSISTANT_NAME`:
@@ -135,5 +156,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)

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`
@@ -82,7 +82,7 @@
 | 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) |
 
 <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.
@@ -90,7 +90,7 @@
 
 ### 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"]
 }
 ```
 
@@ -155,6 +155,22 @@
 - Built on top of the base `nanoclaw-agent-v2-<slug>:latest` image
 - Cached — only rebuilt when package lists change
 
+## Per-agent-group model and effort
+
+Each agent group can override the model and reasoning effort used by its provider. These options are stored in `container_configs` and materialized into `container.json` at spawn time:
+
+```json
+{
+  "model": "sonnet",
+  "effort": "high"
+}
+```
+
+- **`model`** — model alias (`sonnet`, `opus`, `haiku`) or full model ID. Passed straight through to the provider SDK. If omitted, the SDK default applies.
+- **`effort`** — reasoning effort level (`low`, `medium`, `high`, `xhigh`, `max`). Passed straight through to the provider SDK. If omitted, the SDK default applies.
+
+Both fields are per-agent-group, so different workspaces can use different models or effort budgets without restarting the host.
+
 ## Timeouts
 
 ### Container timeout