Environment variables

Exhaustive list of every environment variable the NanoClaw host, setup wizard, and agent runner read. 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) reads exactly these keys from .env at the project root. Values are never loaded into process.env, so they don’t leak to child processes. For the first eleven, a value already in the process environment takes precedence over .env; ANTHROPIC_BASE_URL is read from .env only.

Variable	Default	Read in	Effect
`ASSISTANT_NAME`	`Andy`	`src/config.ts:28`	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:74`	URL of the OneCLI Agent Vault.
`ONECLI_API_KEY`	—	`src/config.ts:75`	API key for the vault. See Credentials.
`TZ`	system timezone, else `UTC`	`src/config.ts:93`	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:79`	Opt-in CPU cap per agent container, passed through to `docker run --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:80`	Opt-in memory cap per agent container, passed through to `docker run --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.
`NANOCLAW_EGRESS_LOCKDOWN`	`false`	`src/config.ts:84`	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:86`	Name of the locked-down Docker network. Can be set in `.env` or the process environment.
`ONECLI_GATEWAY_CONTAINER`	`onecli`	`src/config.ts:88`	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:35`	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.
`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
`CONTAINER_IMAGE`	per-install tag	`src/config.ts:69`	Full agent image override (name and tag).
`CONTAINER_IMAGE_BASE`	per-install name	`src/config.ts:68`	Base image name override. The default embeds an install slug so two checkouts on one host don’t clobber each other’s image.
`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:134`	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:429`	How agents address the operator — skips the prompt.
`NANOCLAW_AGENT_PROVIDER`	—	`setup/auto.ts:855`	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_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:181`	Set `true` to bake CJK fonts (~200 MB) into the agent image. Read from `.env` by 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:235`	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:893`	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:894`	Bearer token for the custom endpoint. Both URL and token must be set together.
`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 Claude-assisted failure recovery entirely (CI/scripted runs).
`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 only TZ (plus provider-contributed and OneCLI proxy variables) at spawn — src/container-runner.ts:443. 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:260`	Where pre-compaction conversation transcripts are archived as Markdown.
`CLAUDE_TRANSCRIPT_ROTATE_BYTES`	`12582912` (12 MiB)	`agent-runner/src/providers/claude.ts:290`	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:298`	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:311`	Base directory the runner scans for Claude Code project transcripts.
`CLAUDE_CODE_AUTO_COMPACT_WINDOW`	`165000`	`agent-runner/src/providers/claude.ts:404`	Token window at which Claude Code auto-compacts context. Raise for 1M-context model variants.

Line numbers reference nanocoai/nanoclaw at v2.1.38 (b6cb53e) 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)