Skip to main content
NanoClaw configuration is managed through environment variables and the config.ts module.

​
Environment variables

Configuration is read from .env file or process.env.
​
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 WhatsApp number. Set to "true" to enable.
​
CONTAINER_IMAGE
string
default:"nanoclaw-agent:latest"
Docker image to use for agent containers.
​
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: 10MB).
​
IDLE_TIMEOUT
number
default:"1800000"
How long to keep container alive after last result in milliseconds (default: 30 minutes).
​
MAX_CONCURRENT_CONTAINERS
number
default:"5"
Maximum number of concurrent agent containers.
​
TZ
string
default:"system timezone"
Timezone for scheduled tasks (cron expressions). Uses Intl.DateTimeFormat().resolvedOptions().timeZone by default.

​
Configuration constants

Defined in src/config.ts: 
export const POLL_INTERVAL = 2000; // Message loop interval (ms)
export const SCHEDULER_POLL_INTERVAL = 60000; // Task scheduler interval (ms)
export const IPC_POLL_INTERVAL = 1000; // IPC watcher interval (ms)

​
Directory paths

All paths are absolute and resolved from the project root:
​
STORE_DIR
string
{PROJECT_ROOT}/store - Database and persistent storage
​
GROUPS_DIR
string
{PROJECT_ROOT}/groups - Group folders and memory files
​
DATA_DIR
string
{PROJECT_ROOT}/data - Legacy data directory (migrated to SQLite)
​
MOUNT_ALLOWLIST_PATH
string
~/.config/nanoclaw/mount-allowlist.json - Mount security allowlist (never mounted into containers)
​
MAIN_GROUP_FOLDER
string
"main" - Folder name for the main group

​
Trigger pattern

The trigger pattern is generated from ASSISTANT_NAME: 
export const TRIGGER_PATTERN = new RegExp(
  `^@${escapeRegex(ASSISTANT_NAME)}\\b`,
  'i',
);
Matches messages starting with @{ASSISTANT_NAME} (case-insensitive).

​
Timezone configuration

Scheduled tasks use the configured timezone: 
export const TIMEZONE =
  process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone;
This affects cron expression evaluation for scheduled tasks.

​
Example .env file

ASSISTANT_NAME=Andy
ASSISTANT_HAS_OWN_NUMBER=false
CONTAINER_TIMEOUT=1800000
MAX_CONCURRENT_CONTAINERS=5
TZ=America/Los_Angeles

​
Security notes

  • Secrets (API keys, credentials) are NOT read in config.ts
  • Secrets stay on disk and are loaded only where needed (container-runner.ts)
  • This prevents leaking secrets to child processes
  • Mount allowlist is stored OUTSIDE project root and never mounted into containers

Build docs developers (and LLMs) love

Get started for freeTalk to us