Mirror Neuron Documents

Environment Variables

Documentation for Environment Variables.

Environment Variables

This page documents the environment variables used by Mirror Neuron, the CLI, the Python SDK/API, shared skills, and the checked-in blueprints.

Boolean values generally accept 1, true, yes, or on for true and 0, false, no, or off for false when parsed by the shared config helpers. Some legacy toggles only check a smaller set; those differences are called out below.

Run command logging

These variables are read by the shared CLI runner used by both mn blueprint run --folder <bundle> and mn blueprint run <blueprint_id>. They are evaluated on the client side and do not need to be listed in a blueprint manifest pass_env.

Run artifacts are written to /tmp/mn_<job_id>/:

VariableDefaultUsage
MN_RUN_DETACH_LOG_SECONDS30Seconds to keep polling job events after the submit stream detaches. Can be overridden per command with --follow-seconds.
MN_RUN_EVENT_LOG_MAX_BYTES10485760Maximum size of /tmp/mn_<job_id>/events.log before rotating.
MN_RUN_EVENT_LOG_BACKUP_COUNT5Number of rotated events.log.N files to keep.
MN_RUN_LOG_LEVELINFOLog level for /tmp/mn_<job_id>/run.log.
MN_RUN_LOG_MAX_BYTES2097152Maximum size of /tmp/mn_<job_id>/run.log before rotating.
MN_RUN_LOG_BACKUP_COUNT5Number of rotated run.log.N files to keep.
MN_RUN_LOG_POLL_INTERVAL_SECONDS0.5Poll interval used while collecting post-detach events.

Example:

MN_RUN_DETACH_LOG_SECONDS=10 \
MN_RUN_LOG_LEVEL=DEBUG \
MN_RUN_EVENT_LOG_MAX_BYTES=5242880 \
mn blueprint run stream_backpressure_simulation

CLI and SDK connectivity

These variables control how CLI, SDK, and API clients connect to the core gRPC runtime.

VariableDefaultUsed byUsage
MN_GRPC_TARGETlocalhost:55051CLI, Python SDK, APIgRPC target for the local deployed runtime.
MN_CORE_GRPC_TARGETlocalhost:55051APIFallback gRPC target used by the API when MN_GRPC_TARGET is unset.
MN_GRPC_TIMEOUT_SECONDS10CLI, Python SDK, APIPer-RPC timeout. 0, none, or an empty value disables the timeout.
MN_GRPC_AUTH_TOKENemptyCLI, Python SDKOptional bearer token metadata for protected gRPC gateways.
MN_NETWORK_JOIN_TOKEN~/.mn/network.token for mn runtime start and mn node exposeCLI, Python SDKStable token used by cluster join handshakes.
MN_CLI_OUTPUTrichCLISet to plain to avoid Rich output formatting.

CLI, API, SDK, and skill logs

These variables control process-level log files. They are separate from per-run logs under /tmp/mn_<job_id>/.

VariableDefaultUsed byUsage
MN_LOG_LEVELINFOCLI, API, SDK, shared skills, some blueprintsProcess logger level.
MN_LOG_MAX_BYTES1048576CLI, API, SDK, shared skills, some blueprintsMaximum log file size before rotation.
MN_LOG_BACKUP_COUNT5CLI, API, SDK, shared skills, some blueprintsNumber of rotated process log files to keep.
MN_CLI_LOG_PATH~/.mn/logs/cli.logCLICLI process log path.
MN_API_LOG_PATH~/.mn/logs/api.logAPIAPI process log path.
MN_SDK_LOG_PATH~/.mn/logs/sdk.logPython SDKSDK process log path.
MN_SKILL_LOG_PATH~/.mn/logs/skills.logShared skillsShared skill log path.
MN_BLUEPRINT_LOG_PATH/tmp/mn-business-email.logBusiness email blueprintBusiness email blueprint log path.
MN_BLUEPRINT_LOG_LEVELunsetBlueprint manifest mappingsGeneric blueprint log-level input mapped by many checked-in manifests.

Web UI

These variables are read by mn-web-ui.

VariableDefaultUsage
MN_WEB_API_BASE_URL/api/v1REST API base URL for the web UI.
MN_WEB_API_TOKENemptyOptional bearer token for protected API instances.

Core runtime

These variables are read by the Elixir core runtime.

VariableDefaultUsage
MN_ENVdevRuntime environment. Must be dev, test, or prod. Production requires a non-default MN_COOKIE.
MN_REDIS_URLredis://127.0.0.1:6379/0Redis URL used by the runtime. Must use redis:// or rediss://.
MN_REDIS_NAMESPACEmirror_neuronRedis key namespace. Use a unique value for isolated test runs.
MN_REDIS_HA_MODEsingleRedis mode. Use single for MN_REDIS_URL or sentinel for Redis Sentinel HA.
MN_REDIS_SENTINELSemptyComma-separated Sentinel endpoints such as 192.168.4.29:26379,192.168.4.35:26379. Required when MN_REDIS_HA_MODE=sentinel.
MN_REDIS_SENTINEL_MASTERmirror-neuronSentinel master name to resolve.
MN_REDIS_SENTINEL_HOST_MAPemptyOptional comma-separated hostname rewrite map, such as host.docker.internal=127.0.0.1, for NAT or Docker test environments.
MN_REDIS_DB0Redis database number used in Sentinel mode.
MN_REDIS_USERNAMEunsetOptional Redis ACL username.
MN_REDIS_PASSWORDunsetOptional Redis password.
MN_REDIS_SENTINEL_USERNAMEunsetOptional Sentinel ACL username.
MN_REDIS_SENTINEL_PASSWORDunsetOptional Sentinel password.
MN_REDIS_WAIT_REPLICAS0Optional Redis WAIT acknowledgement count after durable writes. Use 1 or higher for reliability-first HA writes.
MN_REDIS_WAIT_TIMEOUT_MS100Timeout for Redis WAIT durable-write acknowledgement.
MN_REDIS_RECONNECT_ATTEMPTS10Reconnect/retry attempts for reconnectable Redis failures.
MN_REDIS_RECONNECT_BACKOFF_MS250Initial reconnect backoff in milliseconds.
MN_REDIS_RECONNECT_MAX_BACKOFF_MS2000Maximum reconnect backoff in milliseconds.
MN_COOKIEmirrorneuronErlang distribution cookie. Must be changed in prod.
MN_OPENSHELL_BINopenshellOpenShell executable name or path.
MN_TEMP_DIR/tmp/mirror_neuronRuntime temporary directory.
MN_API_ENABLEDtrueEnables the runtime's built-in API listener. False values are 0, false, FALSE, False, or empty.
MN_API_PORT4000 in core, 4001 in Python APIHTTP API port. The core runtime and Python API have different defaults.
MN_GRPC_PORT50051Core gRPC server port.
MN_NETWORK_ONLYfalseRestricts public gRPC to network join and cluster/resource summaries for core-only cluster peers.
MN_NETWORK_JOIN_TOKENunsetJoin token required by ClusterService.NetworkHandshake; mn runtime start and mn node expose derive cluster cookies and network-mode Redis secrets from it.
MN_NETWORK_ADVERTISE_HOSTunsetHost returned by the network handshake for other nodes to reach this runtime.
MN_NETWORK_REDIS_HOSTgenerated internallyDocker-internal Redis host returned by the network handshake.
MN_NETWORK_REDIS_PORTgenerated internallyDocker-internal Redis port returned by the network handshake, normally 6379.
MN_DOCKER_NETWORK_MODEbridge for local Docker Compose startsDocker network identity mode. Use overlay for multi-host Docker clusters or disabled for legacy IP-based Erlang names.
MN_DOCKER_NETWORK_NAMEmirror-neuron-runtimeDocker bridge/overlay network used for runtime aliases.
MN_NODE_ALIASgenerated under ~/.mn/node.aliasStable Docker DNS alias used for alias-based node names such as mirror_neuron@mn-a1b2c3d4.
MN_NODE_ROLEruntimeRuntime node role. control starts only shared/control services; other values start runtime workers.
MN_NODE_NAMEgenerated internallyErlang node name, typically mirror_neuron@<node-alias> for Docker network mode or mirror_neuron@<ip> for legacy IP mode.
MN_CLUSTER_NODESgenerated internallyComma-separated Erlang node names for clustering.
MN_DIST_PORTinternal defaultErlang distribution port inside Docker-network clusters; legacy IP scripts may still expose it.
MN_REDIS_SENTINEL_PORT26379 in cluster scriptsLocal Sentinel port used by Redis HA helper scripts.
MN_REDIS_SENTINEL_QUORUM1 in cluster scriptsSentinel quorum used by Redis HA helper scripts. Use at least three Sentinel voters for production.
MN_REDIS_HA_AUTOCONFIG1 in start_cluster_node.shWhen Sentinel mode is enabled, controls whether the cluster start script runs scripts/redis_ha.sh join.
MN_BUNDLES_DIRunsetDirectory scanned for registered bundles on runtime startup.
MN_BUNDLE_RELOAD_MODEmanifest valueOverrides bundle reload mode for scanned bundles.
MN_BUNDLE_RELOAD_INTERVAL_SECONDSmanifest valueOverrides bundle reload interval for scanned bundles.

Runtime limits and admission control

VariableDefaultUsage
MN_EXECUTOR_MAX_CONCURRENCY4 in runtime, 50 in some container launch helpers, 2 in cluster scriptsDefault executor lease capacity for the default pool.
MN_EXECUTOR_POOL_CAPACITIESunsetComma-separated pool capacities, such as default=4,gpu=1.
MN_DEFAULT_MAX_AGENT_QUEUE_DEPTH100Default max mailbox depth before an agent is saturated.
MN_DEFAULT_AGENT_QUEUE_HIGH_WATERMARK75Default queue depth at which pressure is reported. Must be <= MN_DEFAULT_MAX_AGENT_QUEUE_DEPTH.
MN_DEFAULT_AGENT_QUEUE_LOW_WATERMARK25Default queue depth at which pressure clears. Must be <= MN_DEFAULT_AGENT_QUEUE_HIGH_WATERMARK.
MN_RESOURCE_ADMISSION_ENABLEDtrueEnables resource admission checks. False values include 0, false, FALSE, False, and empty.
MN_MAX_CPU_LOAD_RATIO1.5CPU load threshold for resource admission. Must be greater than 0.
MN_MAX_MEMORY_USED_RATIO0.95Memory used ratio threshold. Must be greater than 0 and <= 1.
MN_MAX_GPU_UTILIZATION_RATIO0.98GPU utilization threshold. Must be greater than 0 and <= 1.
MN_MAX_GPU_MEMORY_USED_RATIO0.98GPU memory threshold. Must be greater than 0 and <= 1.
MN_MAX_COMMAND_LENGTH32768Maximum wrapped command length for OpenShell and HostLocal runners.
MN_MAX_ARTIFACT_BYTES1048576Maximum captured artifact bytes before truncation.
MN_BLUEPRINT_PYTHON_ENVS_DIR$MN_TEMP_DIR/blueprint_python_envsCache root for blueprint-scoped HostLocal Python virtualenvs.
MN_BLUEPRINT_PYTHON_ENV_SETUP_TIMEOUT_MS600000Timeout for waiting on another process to finish creating the same blueprint Python virtualenv.
MN_BUNDLE_CACHE_DIR$MN_TEMP_DIR/bundle_cacheLocal MirrorNeuron bundle cache root; blueprint cleanup reclaims entries whose manifest belongs to a deleted blueprint.
MN_MAX_EVENT_BYTESunsetOptional positive integer validated at startup for event-size limits.
MN_MAX_FAN_OUTunsetOptional positive integer validated at startup for fan-out limits.

Python API

These variables are read by mn-api.

VariableDefaultUsage
MN_API_HOST0.0.0.0Python API bind host.
MN_API_PORT4001Python API bind port.
MN_API_TOKENemptyEnables bearer-token auth when set. Required when MN_ENV=prod.
MN_API_REQUEST_SIZE_LIMIT_BYTES5242880Maximum request body size. Must be greater than 0.
MN_API_CORS_ALLOW_ORIGINSemptyComma-separated CORS allowlist.
MN_API_BASE_URLhttp://localhost:4001/api/v1Used by system e2e tests as the API base URL.

Context Engine

These variables are used by runtime preflight checks and context-aware blueprints.

VariableDefaultUsage
CONTEXT_ENGINE_ADDRtries localhost:50052, 127.0.0.1:50052, host.docker.internal:50052Context Engine endpoint. Manifest preflight uses this when requiredContextEngine=true; context-aware blueprint workers also use it directly.
CONTEXT_ENGINE_READY_TIMEOUT_MS500Preflight TCP readiness timeout in milliseconds. Takes precedence over seconds.
CONTEXT_ENGINE_READY_TIMEOUT_SECONDS0.5 in blueprint workers, 0.5 equivalent in preflightReadiness timeout in seconds. Used when millisecond timeout is unset.
CONTEXT_REDIS_URLunsetOptional Redis URL read by finance compliance context helpers when the source does not provide one.

Context view logging

These variables are currently used by context-memory blueprints such as context_memory_audit and context_memory_compression.

VariableDefaultUsage
MN_CONTEXT_VIEW_LOGdisabledEnables context-view logging when set to 1, true, yes, or on.
MN_CONTEXT_VIEW_LOG_DESTbothDestination for context-view logs. Supported values are stdout, file, both, and cloud.
MN_CONTEXT_VIEW_LOG_FILE/tmp/mn-context-agent/context_views.jsonlJSONL file path for context-view logs.
MN_CONTEXT_VIEW_LOG_LEVELINFOLogger level for context-view logs.
MN_CONTEXT_VIEW_LOG_MAX_BYTES10485760Maximum context-view log size before rotation.
MN_CONTEXT_VIEW_LOG_BACKUP_COUNT5Number of rotated context-view logs to keep.

Blueprint and model provider variables

Blueprint manifests decide which process environment variables are passed to workers. A variable listed here still needs to be included in a blueprint's pass_env or explicit env mapping before a sandboxed worker can see it.

LLM-enabled blueprints use MN_LLM_* settings as the primary contract. Legacy LITELLM_* aliases are still supported by shared skills when they are safe for the selected provider.

VariableDefaultUsage
MN_BLUEPRINT_QUICK_TESTdisabledEnables quick/test mode in blueprint helpers when set to 1, true, yes, or on.
MN_BLUEPRINT_IDunsetExplicit blueprint identity injected by catalog runs and used for resource ownership/cleanup.
MN_BLUEPRINT_RESOURCE_STALE_SECONDS3600Minimum age before mn blueprint cleanup removes stale incomplete blueprint resources, orphaned generated bundles, or setup locks.
MN_GENERATED_BLUEPRINT_BUNDLES_DIR~/.mn/generated_blueprint_bundlesRoot for generated Python workflow bundles and cleanup of source-mode blueprint artifacts.
MN_CONFIG_PATH~/.mn/config.jsonShared blueprint-support user config path.
MN_RUN_IDgeneratedOptional stable run ID for blueprint runs and specialized worker contracts.
MN_RUNS_ROOT~/.mn/runsOverrides the local run-store root.
MN_NO_RUN_STOREdisabledDisables run-store writes when set to a truthy value.
MN_DISABLE_RUN_STOREdisabledAlias used by worker contracts to disable run-store writes.
MN_BLUEPRINT_CONFIG_PATHunsetWorker-contract config file override.
MN_BLUEPRINT_CONFIG_JSONunsetWorker-contract inline config JSON override.
MN_MODEL_CATALOG_PATHunsetOptional JSON model catalog override merged before ~/.mn/models/catalog.json.
MN_LLM_PROVIDERblueprint-specificLLM provider. docker_model_runner enables MirrorNeuron local model runtime behavior.
MN_LLM_MODELai/gemma4:E2B for Docker Model Runner, otherwise blueprint-specificResolved API model name for LLM-enabled blueprint workers.
MN_LLM_RUNTIME_MODELai/gemma4:E2B for gemma4:e2bDocker Model Runner model reference used by mn model install and validation.
MN_LLM_API_BASEhttp://localhost:12434/engines/v1 for HostLocal Docker Model Runner workersOpenAI-compatible LLM API base. Container/sandbox workers use http://model-runner.docker.internal/engines/v1.
MN_LLM_BACKENDllama.cppDocker Model Runner backend selected for runtime-managed models.
MN_LLM_CONTEXT_SIZEmodel defaultContext size requested for runtime-managed local models.
MN_LLM_TIMEOUT_SECONDS60 where shared skills provide a defaultOptional timeout used by shared LLM skill workers.
MN_LLM_MAX_TOKENS800 where shared skills provide a defaultOptional max output token limit used by shared LLM skill workers.
MN_LLM_NUM_RETRIES2 where shared skills provide a defaultOptional provider retry count.
MN_LLM_RETRY_BACKOFF_SECONDS1.0 where shared skills provide a defaultOptional exponential retry backoff base for direct HTTP fallbacks.
LITELLM_MODELblueprint-specificLegacy LiteLLM model alias. Prefer MN_LLM_MODEL in new blueprints.
LITELLM_API_BASEprovider-specificLegacy LiteLLM API base alias. Prefer MN_LLM_API_BASE in new blueprints.
LITELLM_API_KEYunsetOptional LiteLLM provider API key. Not required for local Ollama.
LITELLM_TIMEOUT_SECONDS60Optional timeout used by shared LLM skill workers.
LITELLM_MAX_TOKENS800Optional max output token limit used by shared LLM skill workers.
LITELLM_NUM_RETRIES2Optional provider retry count. Passed to LiteLLM when available.
LITELLM_RETRY_BACKOFF_SECONDS1.0Optional exponential retry backoff base for direct HTTP fallbacks.

Email and web integration variables

VariableDefaultUsage
RESEND_API_KEYunsetResend API key for email sending skills.
RESEND_FROM_EMAILunsetSender email for Resend delivery.
RESEND_API_BASE_URLhttps://api.resend.comResend API base URL.
AGENTMAIL_API_KEYunsetAgentMail API key for email receive/delivery skills.
AGENTMAIL_INBOXunsetAgentMail inbox ID.
AGENTMAIL_API_BASE_URLhttps://api.agentmail.toAgentMail API base URL.
SCRAPINGBEE_API_KEYunsetScrapingBee API key used by the web fetch skill when configured.
MN_SLACK_BOT_TOKENunsetSlack bot token used by email delivery skills. Falls back to SLACK_BOT_TOKEN in those skills.
MN_SLACK_DEFAULT_CHANNELunsetDefault Slack channel for email delivery skills. Falls back to SLACK_DEFAULT_CHANNEL.
MN_SLACK_API_BASE_URLSlack API defaultSlack API base URL override for email delivery skills.
SLACK_BOT_TOKENunsetSlack bot token fallback used by Slack-related skills and the finance Slack monitor blueprint.
SLACK_DEFAULT_CHANNEL#claw in finance Slack monitorSlack channel fallback used by Slack-related skills and the finance Slack monitor blueprint.

Business email blueprint variables

These are specific to business_customer_lifecycle_email_copilot.

VariableDefaultUsage
SYNAPTIC_DB_CONNECTIONunsetExternal database connection string.
SYNAPTIC_DB_PATHblueprint default or required by workerSQLite database path override.
SYNAPTIC_QUICK_TEST_MODEdisabledEnables reduced quick-test behavior.
SYNAPTIC_EMAIL_DRY_RUNdisabledPrevents real email delivery when enabled.
SYNAPTIC_EMAIL_DELIVERY_MODEblueprint-specificControls email delivery mode.
SYNAPTIC_TEST_EMAIL_TOunsetTest recipient override.
SYNAPTIC_EMIT_CYCLE_TRIGGERtrueSet to false to suppress cycle trigger emission.

Runtime-injected worker variables

The runtime injects these into worker processes. They are normally not set manually.

VariableUsage
MN_INPUT_FILEPath to the worker input payload JSON.
MN_MESSAGE_FILEPath to an injected message JSON file for message/body runner cases.
MN_BODY_FILEPath to an injected body file for message/body runner cases.
MN_BODY_CONTENT_TYPEContent type for MN_BODY_FILE.
MN_BODY_CONTENT_ENCODINGContent encoding for MN_BODY_FILE.
MN_CONTEXT_FILEPath to the worker context JSON file.
MN_AGENT_TYPEAgent type for the current worker.
MN_AGENT_TEMPLATEAgent template type for the current worker.
MN_JOB_IDCurrent runtime job ID.
MN_AGENT_IDCurrent runtime agent ID.
MN_WORKDIRWorker working directory used by runtime tests and some sandbox flows.
MN_EXIT_CODEInternal wrapper variable used to report process exit status.

Test-only variables

These variables are used by tests or helper scripts, not by normal production runs.

VariableDefaultUsage
MN_SECURITY_STRICT0System tests fail hard on security findings when set to 1.
RUN_AGENTMAIL_E2EdisabledEnables real AgentMail e2e tests when set to 1.
RUN_AGENTMAIL_INTEGRATIONdisabledEnables business email AgentMail integration tests when set to 1.
AGENTMAIL_E2E_TIMEOUT_SECONDS60Timeout for AgentMail e2e tests.
RESEND_TEST_TOunsetRecipient used by live Resend email tests and business email test config.
RUN_RESEND_E2EdisabledEnables real Resend e2e tests when set to 1.
MN_HOMEunsetInstallation path referenced by docs/examples when running blueprints from a separate checkout.
MN_LOG_PATHscript-specificLog file path used by cluster e2e helper scripts.
MN_REMOTE_ROOTscript-specificRemote project root used by cluster e2e scripts.
MN_STREAM_WAIT_TIMEOUT_SECONDS120Wait timeout used by streaming cluster e2e scripts.
MN_LLM_WAIT_TIMEOUT_SECONDS300Wait timeout for LLM codegen cluster e2e scripts.
MN_SIM_WAIT_TIMEOUT_SECONDS420Wait timeout for ecosystem simulation cluster e2e scripts.
MN_GEMINI_MODELgemini-2.5-flash-liteGemini model used by LLM codegen cluster e2e scripts.
MN_REDIS_PORT6379Redis port used by cluster helper scripts.
MN_REDIS_TEST_IMAGEredis:7Redis Docker image used by Sentinel HA smoke tests.
MN_REDIS_HA_LOCAL_IPunsetLocal IP override for test_redis_sentinel_two_box_ha.sh.
MN_REDIS_HA_REMOTE_IPunsetRemote IP override for test_redis_sentinel_two_box_ha.sh.
MN_REDIS_HA_TEST_REDIS_PORT46379Host Redis port used by the two-box Sentinel smoke test.
MN_REDIS_HA_TEST_SENTINEL_PORT46380Host Sentinel port used by the two-box Sentinel smoke test.
MN_REDIS_HA_TEST_SSH_OPTS-o BatchMode=yes -o ConnectTimeout=10SSH options used by the two-box Sentinel smoke test.
MN_REDIS_HA_TEST_REMOTE_NETWORKautoRemote Docker network mode for the two-box Sentinel smoke test. Supported values: auto, host, bridge.
MN_REDIS_HA_TEST_INITIAL_PRIMARYautoInitial Redis primary for the two-box Sentinel smoke test. Supported values: auto, local, remote.
MN_CLI_DIST_PORT4371Erlang distribution port used by cluster_cli.sh.
MN_TEST_TOOL_BINunsetTest helper binary override used by selected tests.

On this page