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 is read by the installed gateway, process environment first, then .env. 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:31`	Assistant name. Also sets the default trigger, `@<name>`.
`ASSISTANT_HAS_OWN_NUMBER`	`false`	`src/config.ts:64`	Set `true` when the assistant runs on its own WhatsApp number instead of yours.
`ONECLI_URL`	—	OneCLI gateway skill (`src/gateway-providers/onecli.ts`)	URL of the OneCLI Agent Vault. Read only when the OneCLI gateway is installed.
`ONECLI_API_KEY`	—	OneCLI gateway skill	API key for the vault. Read only when the OneCLI gateway is installed. See Credentials.
`TZ`	system timezone, else `UTC`	`src/config.ts:132`	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:96`	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:97`	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:104`	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:108`	Set `true` to force all agent traffic through the selected credential gateway (OneCLI or Iron Proxy) 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:110`	Name of the locked-down Docker network. Can be set in `.env` or the process environment.
`ONECLI_GATEWAY_CONTAINER`	`onecli`	OneCLI gateway skill	Name of the OneCLI gateway container attached as the only egress hop. Can be set in `.env` or the process environment.
`NANOCLAW_ABSOLUTE_CEILING_MS`	`1800000` (30 minutes)	`src/config.ts` → `src/reconcile-session.ts`	Heartbeat ceiling for a running container, in milliseconds: the host sweep kills a container whose heartbeat is older than this, or older than the declared timeout of a running Bash command if that is longer. A whole number from `60000` to `86400000` (24 hours); anything else is logged and ignored, and the default applies. Process environment, then `.env`, read once at host start. Added after v2026.10.0. See Container killed mid-task.
`NANOCLAW_CLAIM_STUCK_MS`	`60000` (60 seconds)	`src/config.ts` → `src/reconcile-session.ts`	Claim-stuck tolerance, in milliseconds: the host sweep kills a container that picked up a message and has written no heartbeat since, once the claim is older than this (or than a longer declared Bash timeout). A whole number from `10000` to `86400000`; anything else is logged and ignored, and the default applies. Independent of the ceiling. Process environment, then `.env`, read once at host start. Added after v2026.10.0.
`DEFAULT_AGENT_PROVIDER`	`claude`	`src/config.ts:38`	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`	Install-wide default for the Claude fast serving tier, enabled only by `1` or `true` (case-insensitive). Other values stay off. May change provider billing. A group’s own `speed` setting (`ncl groups config update --speed`) overrides it; `--speed ""` returns the group to this default. Other providers must declare speed tiers to use it.
`NANOCLAW_RUNTIME_DRIVER`	`docker`	`src/drivers/index.ts`	Registered session driver. Process environment, then `.env`; unknown names abort startup.
`NANOCLAW_GATEWAY_PROVIDER`	the only installed gateway	`src/gateway-providers/index.ts`	Registered gateway provider: `onecli` or `iron-proxy`. Process environment, then `.env`. Unset works only when exactly one gateway is installed; with more than one installed, startup fails until this is set. Unknown names fail instead of disabling the gateway. See Credential gateways.
`NANOCLAW_SESSION_MATERIAL_ROOT`	`data/session-materials`	`src/drivers/index.ts`	Root for materialized session files. Process environment, then `.env`.
`NANOCLAW_GATEWAY_READ_ONLY_HOSTS`	—	`src/gateway-read-policy.ts`	Comma-separated hostnames (for example `docs.example.com`) whose GET and HEAD requests through the gateway are approved without an approval card. Each entry must be a plain hostname: URLs, wildcards and ports make the whole list invalid, and then nothing is auto-approved. Process environment, then `.env`.
`NANOCLAW_GATEWAY_UNCREDENTIALED_READS`	`false`	`src/gateway-read-policy.ts`	Set `true` to skip the approval card for a GET or HEAD request that sends no body, when the gateway reports that no stored credential applies to that host. The egress allowlist still limits where it can go. Process environment, then `.env`.
`WEBHOOK_PORT`	`3000`	`src/config.ts:121`	Port for the local webhook server. Process environment, then `.env`, resolved when the listener starts. Must be an integer from 1 to 65535; anything else is a startup error.
`ANTHROPIC_BASE_URL`	—	gateway skill (`onecli.ts`, `iron-proxy.ts`)	Custom Anthropic-compatible endpoint, passed into agent containers with a placeholder auth token. Read from the process environment, then `.env`, by the installed gateway. Setup writes it when you configure a custom endpoint; the real token stays in the gateway.

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:87`	Full agent image override (name and tag).
`CONTAINER_IMAGE_BASE`	per-install name	`src/config.ts:86`	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:80`	Local directory templates resolve against; `--template <ref>` is relative to it. Setup’s library picker and an agent’s `create_agent` copy templates from the public library into it (`create_agent` added after v2026.10.0). 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.
`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. The sweep’s two kill timers are tuned install-wide with NANOCLAW_ABSOLUTE_CEILING_MS and NANOCLAW_CLAIM_STUCK_MS instead.

Outbound proxy

If the host reaches the internet through an HTTP or HTTPS proxy, set these in the shell that runs the service setup step, or in .env. The setup step reads them and writes them into the service definition, so the running host picks them up. Changing them later means re-running the service step.

Variable	Default	Effect
`HTTPS_PROXY`	—	Proxy for HTTPS requests. Falls back to `ALL_PROXY`, then `HTTP_PROXY`.
`HTTP_PROXY`	—	Proxy for HTTP requests. Falls back to `ALL_PROXY`, then `HTTPS_PROXY`.
`ALL_PROXY`	—	Fallback for either of the two above.
`NO_PROXY`	`localhost,127.0.0.1,::1,[::1]`	Hosts that skip the proxy. Your entries are added to the loopback defaults.

Only http:// and https:// proxy URLs are used; others are ignored. Setup turns on NODE_USE_ENV_PROXY for the service, which needs Node 22.21+, 24.5+ or 25+. On other Node versions the host goes direct and setup warns.

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:201`	Comma-separated step names to skip: `environment`, `container`, `gateway`, `auth`, `mounts`, `service`, `cli-agent`, `timezone`, `channel`, `verify`, `first-chat`.
`NANOCLAW_DISPLAY_NAME`	`$USER`	`setup/auto.ts:548`	How agents address the operator — skips the prompt.
`NANOCLAW_AGENT_PROVIDER`	—	`setup/auto.ts:491`	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:257`	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, where the picker otherwise defaults to No template changes. 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:271`	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`	—	`.claude/skills/add-onecli/scripts/setup.ts:405`	Use a remote OneCLI vault instead of installing one locally. Unset means a local vault is installed.
`NANOCLAW_ONECLI_API_TOKEN`	—	`.claude/skills/add-onecli/scripts/setup.ts:437`	Bearer token (`oc_…`) for the remote vault. Required when the host is set.
`NANOCLAW_ANTHROPIC_BASE_URL`	—	`.claude/skills/add-onecli/scripts/auth.ts:111`, `.claude/skills/add-iron-proxy/scripts/auth.ts:86`	Custom Anthropic-compatible endpoint. Setup writes `ANTHROPIC_BASE_URL` to `.env` and stores the token in the vault.
`NANOCLAW_ANTHROPIC_AUTH_TOKEN`	—	`.claude/skills/add-onecli/scripts/auth.ts:112`, `.claude/skills/add-iron-proxy/scripts/auth.ts:87`	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:137`	Use non-interactive Claude assist on step failure instead of interactive handoff.
`NANOCLAW_SKIP_CLAUDE_ASSIST`	—	`setup/lib/claude-assist.ts:107`	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.
`NANOCLAW_SETUP_COMMIT`	on	`setup/lib/setup-commit.ts:160`	Set `0` to stop setup committing the files a skill apply adds (`setup: apply <skill>` commits). Meant for contributors running setup in a dev clone. Without those commits, commit the files yourself before `/update-nanoclaw`.
`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-history.ts:108`	Where pre-compaction conversation transcripts are archived as Markdown.
`CLAUDE_TRANSCRIPT_ROTATE_BYTES`	`12582912` (12 MiB)	`agent-runner/src/providers/claude-history.ts:261`	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-history.ts:262`	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-history.ts:54`	Base directory the runner scans for Claude Code project transcripts.
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	`165000`	`agent-runner/src/providers/claude.ts:202`	Token window at which Claude Code auto-compacts context. Raise for 1M-context model variants. Settable on the host from v2026.10.0: put it in `.env` or the process environment and the Claude provider passes it into the container (`src/providers/claude.ts`). In v2.4.0 and earlier a host value never reaches the container. Must be a positive integer; other values are ignored with a warning. `.env` is read at each container spawn; a process-environment change needs a host restart. Either way, restart affected sessions to apply it.

Line numbers reference nanocoai/nanoclaw at f2224a2f (main after v2026.10.0) and will drift with future releases.

Operating

Internals

Environment variables

Read from .env

Host process environment only

Outbound proxy

Setup-time variables

Container-side variables (agent runner)

​Read from .env

​Host process environment only

​Outbound proxy

​Setup-time variables

​Container-side variables (agent runner)

Read from .env

Host process environment only

Outbound proxy

Setup-time variables

Container-side variables (agent runner)