Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
Environment variables

Configuration is read from .env file or process.env, with hardcoded fallbacks.
​
ASSISTANT_NAME
string
default:"Andy"
Name of the assistant. Used in trigger pattern and message routing.
​
ASSISTANT_HAS_OWN_NUMBER
boolean
default:"false"
Whether the assistant has its own phone number or dedicated account. Set to "true" to enable.
​
CONTAINER_IMAGE
string
default:"nanoclaw-agent-v2-<slug>:latest"
Docker image to use for agent containers. The default is scoped to the checkout path via src/install-slug.ts so multiple NanoClaw installs can coexist on one host.
​
CONTAINER_TIMEOUT
number
default:"1800000"
Container timeout in milliseconds (default: 30 minutes).
​
CONTAINER_MAX_OUTPUT_SIZE
number
default:"10485760"
Maximum container output size in bytes (default: 10 MB).
​
IDLE_TIMEOUT
number
default:"1800000"
How long to keep container alive after last result in milliseconds (default: 30 minutes).
​
ONECLI_URL
string
default:"http://localhost:10254"
URL for the OneCLI Agent Vault that handles credential injection for containers.
​
ONECLI_API_KEY
string
API key for authenticating with the OneCLI Agent Vault. Optional — only needed if your OneCLI instance requires authentication.
​
MAX_MESSAGES_PER_PROMPT
number
default:"10"
Maximum number of messages sent to container agents per prompt.
​
MAX_CONCURRENT_CONTAINERS
number
default:"5"
Maximum number of concurrent agent containers.
​
LOG_LEVEL
string
default:"info"
Logging verbosity. Valid values: debug, info, warn, error, fatal.
​
TZ
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.

​
Timezone configuration

The timezone is resolved through a priority chain:
  1. process.env.TZ
  2. TZ from .env file
  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

All paths are absolute and resolved from the project root:
​
DATA_DIR
string
{PROJECT_ROOT}/data — runtime data directory (central DB, sessions)
​
Central DB
string
{PROJECT_ROOT}/data/v2.db — central database with entity model
​
Sessions
string
{PROJECT_ROOT}/data/v2-sessions/{agent_group_id}/{session_id}/ — per-session databases and files
​
GROUPS_DIR
string
{PROJECT_ROOT}/groups — agent group folders and memory files
​
MOUNT_ALLOWLIST_PATH
string
~/.config/nanoclaw/mount-allowlist.json — mount security allowlist (never mounted into containers)

​
Trigger pattern

The default trigger pattern is generated from ASSISTANT_NAME: 
const DEFAULT_TRIGGER = `@${ASSISTANT_NAME}`;
const TRIGGER_PATTERN = new RegExp(`^${DEFAULT_TRIGGER}\\b`, 'i');
In v2, trigger behavior is controlled per-wiring via engage_mode and engage_pattern rather than a global trigger pattern.

​
Example .env file

ASSISTANT_NAME=Andy
ASSISTANT_HAS_OWN_NUMBER=false
CONTAINER_TIMEOUT=1800000
MAX_CONCURRENT_CONTAINERS=5
TZ=America/Los_Angeles
ONECLI_URL=http://127.0.0.1:10254
With the OneCLI Agent Vault, API keys and OAuth tokens are no longer stored in .env. Secrets are managed via onecli secrets create and injected by the vault at request time.

​
Credential management

Credentials are managed externally via OneCLI — no credential environment variables are needed in .env. Register secrets with OneCLI: 
onecli secrets create --name Anthropic --type anthropic --value YOUR_KEY --host-pattern api.anthropic.com
The @onecli-sh/sdk package’s applyContainerConfig() configures each container’s network to route through the vault, injecting credentials at request time.

​
Security notes

  • 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)
Last modified on April 28, 2026