Configuration

Configuration

Contents

• Environment Files
• Loading Cascade
• Switching Environments
• Required vs. Auto-Generated Values
• Validating Configuration
• Setting Up a New Project
• Security Notes
• Sub-pages

ɳSelf uses a layered .env file system for all configuration. Every service in your stack, Postgres, Hasura, Auth, Nginx, and any optional services, is driven entirely by environment variables. There is no YAML-based config format to learn; you set variables in .env files and the CLI generates the correct docker-compose output automatically.

This page explains which files exist, what each one is for, how they stack together, and how to work with them day to day.

---

Environment Files

File	Purpose	Committed to git
.env.dev	Team defaults , safe base values for local development	Yes
.env.staging	Staging overrides applied when ENV=staging	Yes
.env.prod	Production overrides (non-secret values only)	Yes
.env.secrets	Production secrets , passwords, API keys, tokens	No (gitignored)
.env.local	Personal local overrides , your machine only	No (gitignored)
.env	Highest-priority override , takes precedence over everything	No (gitignored)
.env.computed	Auto-generated by nself build via orchestration.sh. Never hand-edit.	No (gitignored)

The three committed files (.env.dev, .env.staging, .env.prod) contain non-sensitive configuration that the whole team can share. Secret material, database passwords, admin secrets, JWT keys, belongs in .env.secrets or .env.local, which are always gitignored.

---

Loading Cascade

When ɳSelf starts, it loads environment files in a fixed order. Each file that is loaded overrides any variables already set by earlier files. Files that do not exist are silently skipped.

1.  .env.dev        ← base team defaults (always loaded)
2.  .env.staging    ← loaded when ENV=staging
3.  .env.prod       ← loaded when ENV=prod
4.  .env.secrets    ← production secrets (gitignored)
5.  .env.local      ← personal local overrides (gitignored)
6.  .env            ← highest-priority override (gitignored)
7.  .env.computed   ← auto-generated by nself build (gitignored, never hand-edit)

After all files have been loaded, apply_smart_defaults() runs and fills in any variables that were not set by any file. This means you only need to specify the values you actually want to change, everything else gets a sensible default automatically.

A practical example: .env.dev sets HASURA_GRAPHQL_ENABLE_CONSOLE=true. Your .env.prod sets HASURA_GRAPHQL_ENABLE_CONSOLE=false. When you run with ENV=prod, the production file is loaded after the dev file, so the console is disabled. Your .env.local could override that again for a specific machine if needed.

---

Switching Environments

Pass the -e flag (or --env) to any command that spins up services:

# Local development (default — same as omitting -e)
nself start -e dev

# Staging environment
nself start -e staging

# Production environment
nself start -e prod

The ENV variable also accepts common aliases so you do not need to remember the canonical names:

You type	Resolved to
development, develop, devel	dev
production, prod	prod
staging, stage	staging

You can also set ENV directly in your .env or .env.local file if you always work in the same environment on a given machine:

# .env.local
ENV=dev

---

Required vs. Auto-Generated Values

Some variables are required, ɳSelf will refuse to start if they are missing:

• PROJECT_NAME, your project's namespace (lowercase, 2–30 characters)
• POSTGRES_PASSWORD, must be at least 16 characters
• HASURA_GRAPHQL_ADMIN_SECRET, must be at least 32 characters
• HASURA_JWT_KEY, must be at least 32 characters

Other values are auto-generated the first time you run nself init. The CLI writes them into your .env file so they persist across restarts. You should not regenerate these after a project is live, doing so would invalidate all existing sessions and tokens.

When in doubt, run the validation command (see below) to check which required variables are missing.

---

Validating Configuration

Before starting your stack, especially before deploying to production, validate your configuration:

nself config validate

This command loads the full cascade for your current environment and checks every required variable. It reports:

• Missing required values
• Values that fail format validation (e.g., a password that is too short)
• Variables that reference other undefined variables
• Security warnings for production environments (such as wildcard CORS origins)

To validate a specific environment without starting any services:

nself config validate -e prod

You can also print the resolved configuration (all variables after the cascade) to inspect what values the CLI will actually use:

nself config show
nself config show -e prod

---

Setting Up a New Project

For a brand-new project, the typical workflow is:

# 1. Initialise — creates .env.dev with defaults and auto-generates secrets
nself init

# 2. Edit .env.dev to set your project name and domain
#    PROJECT_NAME=myproject
#    BASE_DOMAIN=myproject.local

# 3. For production, copy the secrets template and fill it in
cp .env.secrets.example .env.secrets
# Edit .env.secrets — set your real passwords and keys

# 4. Validate before starting
nself config validate

# 5. Start the stack
nself start

---

Security Notes

• Never commit .env.secrets, it is gitignored by default, but double-check before pushing
• Never put secrets in .env.dev, this file is committed and shared with your team
• In production, set HASURA_GRAPHQL_ENABLE_CONSOLE=false and HASURA_GRAPHQL_DEV_MODE=false
• Use strong, randomly generated passwords (at least 32 characters) for POSTGRES_PASSWORD, HASURA_GRAPHQL_ADMIN_SECRET, and HASURA_JWT_KEY
• Do not reuse the same secrets across projects or environments

---

Plugin Environment Variables (v1.0.3+)

Pro plugins introduce additional environment variables. These are set in .env.secrets (for sensitive values) or .env.dev (for non-sensitive defaults).

Inter-Plugin Authentication

Variable	Purpose	Where
PLUGIN_INTERNAL_SECRET	Shared secret for plugin-to-plugin HTTP calls (X-Internal-Token header)	.env.secrets
CLAW_WEB_SECRET	Authentication secret for the claw-web plugin dashboard	.env.secrets
MUX_CLAW_SHARED_SECRET	Auth token for mux-to-claw RPC calls (POST /internal/classify)	.env.secrets
NOTIFY_INTERNAL_SECRET	Auth for notify plugin internal API	.env.secrets (auto-generated)

AI and Model Routing

Variable	Purpose	Where
NCLAW_FAST_MODEL	Default fast model for ɳClaw routing (e.g., gemini-2.5-flash)	.env.dev
NSELF_VOICE_LLM_PROVIDER	Voice plugin LLM provider	.env.dev
NSELF_VOICE_LLM_MODEL	Voice plugin LLM model	.env.dev
NSELF_VOICE_MODE	Voice mode: standard or realtime	.env.dev
OLLAMA_BASE_URL	Ollama endpoint. Default: http://host.docker.internal:11434	.env.dev
GEMINI_FREE_KEY_1..N	Gemini API keys for tier-1 routing (round-robin)	.env.secrets
GEMINI_FLASH_KEY_1..N	Gemini Flash keys for tier-2 routing	.env.secrets
GEMINI_FLASH_LITE_KEY_1..N	Gemini Flash Lite keys for tier-1	.env.secrets
AI_GOOGLE_API_KEY_1..N	Alternative Google API key prefix (read alongside GEMINI_FREE_KEY_N)	.env.secrets
CLAUDE_OAUTH_REFRESH_*	Claude OAuth refresh tokens for tier-3 routing	.env.secrets
GOOGLE_PRIMARY_USER_ID	Primary Google account ID for google plugin	.env.dev

ɳClaw Behavior

Variable	Purpose	Where
NCLAW_ALLOW_SHELL	Enable shell_dispatch_vps tool (true/false)	.env.dev
NCLAW_QUIET_START / NCLAW_QUIET_END	Quiet hours for proactive notifications (e.g., 22:00/07:00)	.env.dev
NCLAW_DRAFT_APPROVAL	Require Telegram approval for email drafts (true default)	.env.dev
CLAW_BLOCKED_RECIPIENTS	Comma-separated email blocklist	.env.dev
CLAW_TG_ALLOWED_USERS	Telegram user IDs allowed to interact with the claw bot	.env.dev
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google OAuth for Gmail, Calendar, Drive	.env.secrets
CLAW_TG_BOT_TOKEN	Telegram bot token for the claw plugin TG bridge	.env.secrets
GITHUB_TOKEN	GitHub PAT for git_create_pr tool	.env.secrets

Plugin Resource Limits

Variable	Purpose	Default
PLUGIN_{NAME}_MEMORY_LIMIT	Docker memory limit for a specific plugin	varies
PLUGIN_{NAME}_CPU_LIMIT	Docker CPU limit for a specific plugin	varies
PLUGIN_DEFAULT_MEMORY_LIMIT	Default memory limit for all plugins	512m
PLUGIN_DEFAULT_CPU_LIMIT	Default CPU limit for all plugins	0.5

The plugin-ai plugin defaults to 1g memory and 1.0 CPU.

Plugin Shutdown Grace Period

Variable	Purpose	Default
DOCKER_STOP_GRACE_PERIOD	SIGTERM-to-SIGKILL window for plugin shutdown	30s

DOCKER_STOP_GRACE_PERIOD controls how long the CLI waits for a plugin process to shut down cleanly after receiving SIGTERM before sending SIGKILL. Set this in your .env.dev or as a shell export to match your compose layer's stop_grace_period setting:

# In .env.dev (or export before running nself plugin stop):
DOCKER_STOP_GRACE_PERIOD=30s   # default — matches compose stop_grace_period
DOCKER_STOP_GRACE_PERIOD=10s   # faster teardown in CI
DOCKER_STOP_GRACE_PERIOD=60s   # extra time for plugins with long-poll connections

Allowed range: 1s to 120s. Values outside this range are clamped. Invalid values fall back to 30s.

Mux Email Pipeline

Variable	Purpose	Where
MUX_WATCH_RENEWAL_EXTERNAL	Suppress 404 warnings during Gmail watch renewal (true/false)	.env.dev
MUX_ALLOWED_INSERT_TABLES	Tables the mux plugin can insert into (gates query_transactions tool)	.env.dev

Auto-Generated Internal URLs

When pro plugins are installed, nself build auto-generates PLUGIN_{NAME}_INTERNAL_URL variables for inter-plugin communication. See API-Reference for the full mapping.

---

Sub-pages

• Config-Env-Vars -- Complete environment variable reference for every service
• Config-Postgres -- PostgreSQL configuration in depth
• Config-Hasura -- Hasura GraphQL Engine configuration
• Config-Auth -- Authentication service configuration
• Config-Nginx -- Nginx reverse proxy and SSL configuration
• Config-Optional-Services -- Redis, MinIO, Functions, Search, Mail, MLflow, Admin
• Config-Custom-Services -- Custom service slots (CS_1 through CS_10)
• API-Reference -- Plugin REST API endpoints

---

← Home | Getting-Started | Config-Env-Vars →