Environment variables

Core environment settings read by the NanoClaw host, setup wizard, and agent runner. For how to actually set these — .env editing, service definitions, restart commands — see Configuration. Channel adapters (Telegram bot tokens, Slack app credentials, and so on) have their own variables documented on the per-channel pages under Channels; they’re not repeated here.

Read from .env

NanoClaw’s own parser (src/env.ts) returns only the keys requested by each caller from .env at the project root. The parser itself does not load values into process.env. For the core settings below, the process environment takes precedence over .env unless noted. ANTHROPIC_BASE_URL in the Claude provider is read from .env only. The shared parser strips matching outer single or double quotes, ignores blank values, and does not execute shell expressions. These parsing rules apply to callers of readEnvFile/envValue; some setup steps retain their own readers.

Variable	Default	Read in	Effect
`ASSISTANT_NAME`	`Andy`	`src/config.ts:29`	Assistant name. Also sets the default trigger, `@<name>`.
`ASSISTANT_HAS_OWN_NUMBER`	`false`	`src/config.ts:47`	Set `true` when the assistant runs on its own WhatsApp number instead of yours.
`ONECLI_URL`	—	`src/config.ts:75`	URL of the OneCLI Agent Vault.
`ONECLI_API_KEY`	—	`src/config.ts:76`	API key for the vault. See Credentials.
`TZ`	system timezone, else `UTC`	`src/config.ts:101`	IANA timezone for scheduled tasks and timestamps. Invalid values are skipped, not errored. Injected into every agent container at spawn.
`CONTAINER_CPU_LIMIT`	unset (unbounded)	`src/config.ts:80`	Opt-in CPU cap per agent container, passed through to `docker create --cpus` (e.g. `2`). Empty leaves containers unbounded — the current default. Can be set in `.env` or the process environment.
`CONTAINER_MEMORY_LIMIT`	unset (unbounded)	`src/config.ts:81`	Opt-in memory cap per agent container, passed through to `docker create --memory` (e.g. `8g`). A hard cap only on a swapless host — there the runaway is OOM-killed; with swap present the container can spill past it. NanoClaw doesn’t manage swap. Can be set in `.env` or the process environment.
`CONTAINER_PIDS_LIMIT`	`2048`	`src/config.ts:88`	Process/thread cap per agent container, passed through to `docker create --pids-limit` — a fork-bomb backstop, and the one container limit that’s on by default. Set `0` (or any non-numeric value) to drop the cap. Resolved with `??` rather than `	`, so an explicitly empty value in the process environment wins and disables the cap instead of falling through to` .env`or the default. Can be set in`.env` or the process environment.
`NANOCLAW_EGRESS_LOCKDOWN`	`false`	`src/config.ts:92`	Set `true` to force all agent traffic through the OneCLI gateway on an internal Docker network. Spawns fail fast if the gateway isn’t running. Can be set in `.env` or the process environment. See Hardening.
`NANOCLAW_EGRESS_NETWORK`	`nanoclaw-egress`	`src/config.ts:93`	Name of the locked-down Docker network. Can be set in `.env` or the process environment.
`ONECLI_GATEWAY_CONTAINER`	`onecli`	`src/config.ts:95`	Name of the gateway container attached as the only egress hop. Can be set in `.env` or the process environment.
`DEFAULT_AGENT_PROVIDER`	`claude`	`src/config.ts:36`	Instance-wide default agent provider stamped onto newly created agent groups. Existing groups are never retroactively changed, and per-group `ncl groups config update --provider` overrides it. Can be set in `.env` or the process environment.
`NANOCLAW_DEFAULT_MODEL`	provider default	`src/config.ts` → `configFromDb`	Install-wide model used when the group’s model is `NULL`. The group’s own model wins. Restart the host to reload the setting, then restart affected agent sessions to apply it.
`NANOCLAW_FAST_MODE`	`false`	`src/config.ts` → Claude provider `settings.fastMode`	Enables the Claude fast serving tier only for `1` or `true` (case-insensitive). Other values stay off. May change provider billing. No per-group fast-mode field; other providers must explicitly support the option.
`NANOCLAW_RUNTIME_DRIVER`	`docker`	`src/drivers/index.ts`	Registered session driver. Process environment, then `.env`; unknown names abort startup.
`NANOCLAW_GATEWAY_PROVIDER`	`onecli`	`src/gateway-providers/index.ts`	Registered gateway provider. Process environment, then `.env`; unknown names fail instead of disabling the gateway.
`NANOCLAW_SESSION_MATERIAL_ROOT`	`data/session-materials`	`src/drivers/index.ts`	Root for materialized session files. Process environment, then `.env`.
`ANTHROPIC_BASE_URL`	—	`src/providers/claude.ts:21`	Custom Anthropic-compatible endpoint, passed into agent containers with a placeholder auth token. Only active when setup has registered the custom-endpoint provider config; the real token stays in the vault.

Host process environment only

Read from process.env at host startup, with no .env fallback. Putting these in .env has no effect — the generated launchd plist, systemd unit, and nohup wrapper don’t source it. Set them in the service definition or export them before pnpm run dev.

Variable	Default	Read in	Effect
`NANOCLAW_INSTALL_ID`	first 8 characters of SHA-1 of the project-root path (`process.cwd()` by default)	`src/install-slug.ts`	Explicit install identity for deployments where the checkout path is not stable. Must be 1–32 lowercase letters, digits, `_` or `-`, starting with a letter or digit; invalid values throw. No `.env` fallback.
`CONTAINER_IMAGE`	per-install tag	`src/config.ts:70`	Full agent image override (name and tag).
`CONTAINER_IMAGE_BASE`	per-install name	`src/config.ts:69`	Base image name override. The default embeds an install slug so two checkouts on one host don’t clobber each other’s image.
`NANOCLAW_TEMPLATES_DIR`	`templates/` at the project root	`src/config.ts:63`	Local directory templates resolve against; `--template <ref>` is relative to it. A local path only, never a URL. Resolved once at host startup, so setting it on an `ncl` invocation has no effect — `ncl` is a socket client and the host has already resolved the path. Change it in the service definition and restart the host.
`WEBHOOK_PORT`	`3000`	`src/webhook-server.ts:113`	Port for the local webhook server.
`LOG_LEVEL`	`info`	`src/log.ts:16`	One of `debug`, `info`, `warn`, `error`, `fatal`.

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 anywhere (host or container). Container idle/stuck detection is now handled by the periodic host-sweep loop (src/host-sweep.ts), not a per-container timeout env var. Setting any of these five in .env or the process environment has no effect.

Setup-time variables

Consumed by the setup wizard (pnpm run setup:auto) and migration scripts, not by the running host. Most pre-answer an interactive prompt for scripted or CI runs; each also has a matching CLI flag (e.g. NANOCLAW_SKIP ↔ --skip).

Variable	Default	Read in	Effect
`NANOCLAW_SKIP`	—	`setup/auto.ts:164`	Comma-separated step names to skip: `environment`, `container`, `onecli`, `auth`, `mounts`, `service`, `cli-agent`, `timezone`, `channel`, `verify`, `first-chat`.
`NANOCLAW_DISPLAY_NAME`	`$USER`	`setup/auto.ts:536`	How agents address the operator — skips the prompt.
`NANOCLAW_AGENT_PROVIDER`	—	`setup/auto.ts:1220`	Preselects the agent provider and skips the setup picker (e.g. `claude`, `codex`). Setup fails if the value isn’t a provider available in this install.
`NANOCLAW_TEMPLATE_PATH`	—	`setup/auto.ts:221`	Presets the first-agent template as a local ref (e.g. `<category>/<template>`), skipping the picker. Same as `--template-path`. Honored even on an existing install, which otherwise never sees the picker. Setup warns and falls back to the picker if the ref isn’t found.
`NANOCLAW_AGENT_NAME`	—	`setup/channels/*.ts`	Pre-fills the agent name prompt in each channel setup flow. The CLI scratch agent is always “Terminal Agent”.
`NANOCLAW_CHANNELS`	—	`setup/migrate-v2/select-channels.ts:43`	Comma-separated channel names (e.g. `telegram,discord`) — skips the channel picker in the v2 migration flow.
`NANOCLAW_V1_PATH`	sibling-directory scan	`migrate-v2.sh:196`	Explicit override for v1 install discovery in the migration flow. Validated against `$NANOCLAW_V1_PATH/store/messages.db` — the script fails with a message telling you to set it when auto-discovery misses.
`INSTALL_CJK_FONTS`	`false`	`setup/container.ts:273`	Set `true` to bake CJK fonts (~200 MB) into the agent image. Read from `.env` with a dedicated regex during the container build step and passed as a Docker `--build-arg` — the only build-arg passed through today. Set it in `.env`, not the service environment.
`NANOCLAW_ONECLI_API_HOST`	—	`setup/auto.ts:307`	Use a remote OneCLI vault instead of installing one locally. Unset means a local vault is installed; `https://api.onecli.sh` is only the pre-filled placeholder in the advanced-settings form (`setup/lib/setup-config.ts:73`), not a live default.
`NANOCLAW_ONECLI_API_TOKEN`	—	`setup/onecli.ts:325`	Bearer token (`oc_…`) for the remote vault. Required when the host is set.
`NANOCLAW_ANTHROPIC_BASE_URL`	—	`setup/auto.ts:1392`	Custom Anthropic-compatible endpoint. Setup writes `ANTHROPIC_BASE_URL` to `.env` and stores the token in the vault.
`NANOCLAW_ANTHROPIC_AUTH_TOKEN`	—	`setup/auto.ts:1393`	Bearer token for the custom endpoint. Both URL and token must be set together.
`NANOCLAW_HARDENED_IMAGE`	`false`	`setup/container.ts:286`	`true` makes the install pull the pre-built hardened agent image instead of building locally. The setup sign-in writes it to `.env`; read from the environment or `.env`.
`NANOCLAW_AGENT_IMAGE_REF`	—	`setup/container.ts:309`	Image reference to pull, ideally digest-pinned (`repo@sha256:…`). Overrides the `agent-image` pin in `versions.json`.
`NANOCLAW_REGISTRY_API`	—	`setup/registry-login.ts:65`	Base URL of the registry account service. Unset means the hosted NanoClaw service.
`NANOCLAW_REGISTRY_TOKEN`	—	`setup/registry-login.ts:66`	Adopt an existing account token directly, skipping the browser sign-in.
`NANOCLAW_REGISTRY_ENROLL_CODE`	—	`setup/registry-login.ts:67`	Redeem an enrollment code without a browser (for CI).
`NANOCLAW_ALLOW_UNLABELED_IMAGE`	—	`container/pull.sh:153`	Accept a pulled image with no agent-runner lock label — needed for `docker save`/`load` or third-party images.
`NANOCLAW_SETUP_ASSIST_MODE`	`false`	`setup/lib/setup-config.ts:136`	Use non-interactive Claude assist on step failure instead of interactive handoff.
`NANOCLAW_SKIP_CLAUDE_ASSIST`	—	`setup/lib/claude-assist.ts:97`	Set `1` to disable assisted failure recovery entirely (CI/scripted runs). On a non-Claude install, the picked provider’s own failure assist runs first, with Claude as a guarded fallback.
`NANOCLAW_NO_DIAGNOSTICS`	—	`setup/lib/diagnostics.ts:54`	Set `1` to disable setup diagnostics reporting.
`SIGNAL_CLI_PATH`	`signal-cli` (on `PATH`)	`setup/signal-auth.ts:51`	Path to the `signal-cli` binary for the Signal channel flow.

NANOCLAW_REEXEC_SG and NANOCLAW_BOOTSTRAPPED also appear in setup/auto.ts — they’re internal sentinels setup sets on itself when re-executing (Linux sg docker re-exec, bootstrap guard). Don’t set them yourself.

Container-side variables (agent runner)

Read inside the agent container by the agent runner. The host injects runtime, routing, and provider/gateway variables at spawn; these are not a blanket passthrough of the host environment. The rest are not passed through from the host environment; overriding them means baking them into a custom image or a provider container config.

Variable	Default	Read in	Effect
`TZ`	injected from host `TIMEZONE`	`agent-runner/src/timezone.ts:68`	Timezone for timestamps and scheduling inside the container.
`NANOCLAW_CONVERSATIONS_DIR`	`/workspace/agent/conversations`	`agent-runner/src/providers/claude.ts:309`	Where pre-compaction conversation transcripts are archived as Markdown.
`CLAUDE_TRANSCRIPT_ROTATE_BYTES`	`12582912` (12 MiB)	`agent-runner/src/providers/claude.ts:339`	Transcript size past which the session is rotated instead of resumed — cold resumes of huge transcripts would outlive the idle ceiling.
`CLAUDE_TRANSCRIPT_ROTATE_AGE_DAYS`	`14`	`agent-runner/src/providers/claude.ts:347`	Age trigger for transcript rotation, measured from the first entry. Zero or negative disables the age check; size alone governs.
`CLAUDE_CONFIG_DIR`	`~/.claude`	`agent-runner/src/providers/claude.ts:360`	Base directory the runner scans for Claude Code project transcripts.
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	`165000`	`agent-runner/src/providers/claude.ts:453`	Token window at which Claude Code auto-compacts context. Raise for 1M-context model variants.

Line numbers reference nanocoai/nanoclaw at 639577c3 (v2.1.54) and will drift with future releases.

Operating

Internals

Environment variables

Read from .env

Host process environment only

Setup-time variables

Container-side variables (agent runner)

​Read from .env

​Host process environment only

​Setup-time variables

​Container-side variables (agent runner)

Read from .env

Host process environment only

Setup-time variables

Container-side variables (agent runner)