Configuration

NanoClaw has two configuration layers:

Install-wide environment variables — identity, container limits, logging, credentials. They apply to the whole install.
Per-group container config in the database — each agent group has a row in the container_configs table controlling its provider, model, mounts, packages, and MCP servers.

Environment variables

Variables come from two sources, and the distinction matters:

A small set is read from .env at the project root by NanoClaw’s own parser. These work with a plain “edit .env, restart” flow. Values are not loaded into process.env, so secrets don’t leak to child processes; a value already in the process environment takes precedence.
The process-only settings listed below are read from process.env only. The launchd plist and systemd unit that setup generates set PATH and HOME, plus the outbound proxy variables when a proxy is configured (see Environment variables). The nohup wrapper loads only that proxy file. None of them source .env. Putting these variables in .env has no effect; you have to set them in the service environment (see Applying changes).

Read from .env

Variable	Default	What it does
`ASSISTANT_NAME`	`Andy`	The assistant’s name. Also sets the default trigger, `@<name>`.
`ASSISTANT_HAS_OWN_NUMBER`	`false`	Set `true` when the assistant runs on its own WhatsApp number instead of yours.
`DEFAULT_AGENT_PROVIDER`	`claude`	Provider stamped on new agent groups at creation. Existing groups are never touched, and the per-group `provider` config still wins.
`NANOCLAW_DEFAULT_MODEL`	provider SDK default	Model used at the next spawn for groups without their own model. Unlike the provider default, this is not stamped at group creation.
`NANOCLAW_FAST_MODE`	`false`	Enables the faster, higher-priced serving tier for the Claude provider. Only `1` or `true` enables it, case-insensitively.
`NANOCLAW_RUNTIME_DRIVER`	`docker`	Selects an installed session driver. Docker is the only driver shipped here; an unregistered value fails.
`NANOCLAW_GATEWAY_PROVIDER`	the only installed gateway	Selects an installed credential-gateway provider (`onecli` or `iron-proxy`). Unset works only when exactly one gateway is installed. An unregistered value fails. See Credential gateways.
`NANOCLAW_SESSION_MATERIAL_ROOT`	`data/session-materials`	Host directory admitted for session identity material.
`WEBHOOK_PORT`	`3000`	Port for the local webhook server. Process environment first, then `.env`. Must be an integer from 1 to 65535.
`ONECLI_URL`	—	URL of the OneCLI Agent Vault.
`ONECLI_API_KEY`	—	API key for the vault. See Credentials.
`TZ`	system timezone, else `UTC`	IANA timezone for scheduled tasks and message timestamps. Invalid values are skipped, not errored.
`CONTAINER_CPU_LIMIT`	unset (unbounded)	Opt-in CPU cap per container, passed to `docker create --cpus` (e.g. `2`). Can be set in `.env` or the process environment.
`CONTAINER_MEMORY_LIMIT`	unset (unbounded)	Opt-in memory cap per container, passed to `docker create --memory` (e.g. `8g`). Hard cap only on a swapless host. Can be set in `.env` or the process environment.
`CONTAINER_PIDS_LIMIT`	`2048`	Process and thread cap per container, passed to `docker create --pids-limit`. The one container limit that is on by default. Set `0` or a non-numeric value to drop the cap. Can be set in `.env` or the process environment.
`NANOCLAW_EGRESS_LOCKDOWN`	`false`	Set `true` to force all agent traffic through the selected credential gateway (OneCLI or Iron Proxy) on an internal Docker network. Fails fast if the gateway isn’t running. Can be set in `.env` or the process environment. See Hardening.
`NANOCLAW_EGRESS_NETWORK`	`nanoclaw-egress`	Name of the locked-down Docker network. Can be set in `.env` or the process environment.
`ONECLI_GATEWAY_CONTAINER`	`onecli`	Name of the gateway container attached as the only egress hop. Can be set in `.env` or the process environment.
`NANOCLAW_ABSOLUTE_CEILING_MS`	`1800000` (30 minutes)	Milliseconds a running container can go without a heartbeat before the host sweep kills it. A whole number from `60000` (1 minute) to `86400000` (24 hours); any other value is logged and ignored, and the default applies. Raise it when a slow model, often a local one, stays silent for a long time inside one turn. Process environment first, then `.env`. Read when the host starts. Added after v2026.10.0. See Container killed mid-task.
`NANOCLAW_CLAIM_STUCK_MS`	`60000` (60 seconds)	Milliseconds a container can hold a message it picked up, with no heartbeat since, before the host sweep kills it. A whole number from `10000` (10 seconds) to `86400000` (24 hours); any other value is logged and ignored, and the default applies. Raise it only when the agent takes longer than this to report its first event after picking up a message. Independent of `NANOCLAW_ABSOLUTE_CEILING_MS`. Process environment first, then `.env`. Read when the host starts. Added after v2026.10.0.
`ANTHROPIC_BASE_URL`	—	Custom Anthropic-compatible endpoint for the Claude provider. Only active when setup has configured a custom endpoint; the real auth token stays on the host and is injected by the OneCLI proxy.

Host and setup settings

Host-only settings need the service environment or an exported value in your dev shell. Setup also reads NANOCLAW_HARDENED_IMAGE and NANOCLAW_AGENT_IMAGE_REF from .env, with the process environment taking precedence. Containers

Variable	Default	What it does
`CONTAINER_IMAGE`	per-install tag	Full agent image override (name and tag).
`CONTAINER_IMAGE_BASE`	per-install name	Base image name override. The default includes an install slug so two checkouts on one host don’t clobber each other’s `nanoclaw-agent` image.
`NANOCLAW_HARDENED_IMAGE`	`false`	Set `true` to fetch the pre-built Echo hardened image at the next build/install step instead of building locally (`setup/container.ts:286`).
`NANOCLAW_AGENT_IMAGE_REF`	committed `agent-image` pin in `versions.json`	Override which pullable image reference to fetch (`setup/container.ts:309`).
`NANOCLAW_ALLOW_UNLABELED_IMAGE`	`false` (unset)	Accept a pulled image with no `dev.nanoclaw.agent-runner-lock-sha256` label instead of refusing it (`container/pull.sh:153`). See Hardening.

See the environment variables reference for the full list.

CONTAINER_TIMEOUT, IDLE_TIMEOUT, MAX_CONCURRENT_CONTAINERS, CONTAINER_MAX_OUTPUT_SIZE, and MAX_MESSAGES_PER_PROMPT were removed from the code and are no longer read — setting any of them has no effect. Container idle/stuck detection is now handled by the periodic host-sweep loop (src/host-sweep.ts), not a per-container timeout env var. The sweep’s two kill timers are set install-wide with NANOCLAW_ABSOLUTE_CEILING_MS and NANOCLAW_CLAIM_STUCK_MS (above).

Network and logging

Variable	Default	What it does
`LOG_LEVEL`	`info`	One of `debug`, `info`, `warn`, `error`, `fatal`.

See Hardening for the full egress lockdown and sandboxing story.

Per-group container config

Each agent group has a row in the container_configs table (the central SQLite database). At spawn time NanoClaw materializes it to groups/<folder>/container.json — don’t edit that file by hand, it’s overwritten on every spawn. The full per-field reference, including the variable tables for the whole install, lives in the environment variables and container configuration references. Fields per group:

Field	What it controls
`provider`	Which agent CLI runs in the container (e.g. Claude Code, OpenCode). New groups start with the `DEFAULT_AGENT_PROVIDER` value.
`model`, `effort`	Model and reasoning effort passed to the provider.
`assistant_name`	Per-group assistant name override.
`max_messages_per_prompt`	Maximum inbound messages supplied in one provider turn for this group.
`timezone`	IANA timezone for this group. Overrides the install timezone for scheduled tasks and the container’s `TZ`. Unset or invalid falls back to the install timezone.
`speed`	Provider-declared speed tier for this group (Claude: `standard` or `fast`). Empty follows the install default (`NANOCLAW_FAST_MODE`).
`image_tag`	Custom container image for this group.
`cli_scope`	What the group’s agent can do via the internal CLI: `disabled`, `group` (own group only, the default), or `global`.
`skills`	Skill list for the group, or `all`.
`mcp_servers`	MCP servers available inside the container.
`packages_apt`, `packages_npm`	Extra packages installed in the container.
`additional_mounts`	Extra host directories mounted into the container (subject to the mount allowlist at `~/.config/nanoclaw/mount-allowlist.json`).

To change a group’s config, ask the agent in that group, or use ncl. For adding MCP servers, mounts, and providers, see Extending NanoClaw and Ollama integration.

Applying changes

.env-read variables: edit .env, then restart the service:

# macOS
launchctl kickstart -k gui/$(id -u)/com.nanoclaw-v2-<slug>

# Linux
systemctl --user restart nanoclaw-v2-<slug>

A host restart can adopt containers that are already running. After changing NANOCLAW_DEFAULT_MODEL, NANOCLAW_FAST_MODE, or another spawn-time setting, also run ncl groups restart --id <group-id> for each affected group to apply it. Process-environment variables: add them to the service definition, then reload it.

macOS: edit ~/Library/LaunchAgents/com.nanoclaw-v2-<slug>.plist, add a key to the EnvironmentVariables dict, then launchctl unload + launchctl load the plist.
Linux (systemd): add an Environment=KEY=value line to the unit, then systemctl --user daemon-reload && systemctl --user restart nanoclaw-v2-<slug>.
Dev shell: export LOG_LEVEL=debug before pnpm run dev.

Re-running the service setup step regenerates the plist or unit file, wiping manual Environment edits — re-apply them afterwards.

Per-group container config applies at the next container spawn — it’s read fresh from the database each time. A running container keeps its old config until it’s restarted, and package changes need an image rebuild (ncl groups restart --id <group-id> --rebuild). See the container configuration reference for per-field semantics. See Installation for service management details and finding your install slug.

Get started

Channels

Operate

Build with agents

Templates

Extend

Understand

Changelog

Environment variables

Read from .env

Host and setup settings

Per-group container config

Applying changes

​Environment variables

​Read from .env

​Host and setup settings

​Per-group container config

​Applying changes

Environment variables

Read from .env

Host and setup settings

Per-group container config

Applying changes