> ## Documentation Index > Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt > Use this file to discover all available pages before exploring further. # Environment variables > Every environment variable NanoClaw reads — .env keys, host process environment, setup-time variables, and container-side overrides — with defaults and source locations. 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](/operate/configuration). Channel adapters (Telegram bot tokens, Slack app credentials, and so on) have their own variables documented on the per-channel pages under [Channels](/channels/overview); they're not repeated here. ## Read from .env NanoClaw's own parser ([`src/env.ts`](https://github.com/nanocoai/nanoclaw/blob/main/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 twelve, 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:29` | Assistant name. Also sets the default trigger, `@`. | | | | `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](/operate/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 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:81` | 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. | | | | `CONTAINER_PIDS_LIMIT` | `2048` | `src/config.ts:88` | Process/thread cap per agent container, passed through to `docker run --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](/operate/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. | | | | `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: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. | | `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:485`. 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`](https://github.com/nanocoai/nanoclaw) at `f1e66179` (v2.1.53) and will drift with future releases.