Config Overrides#

MiMo Code runtime parameters come from three places: the user config file, command-line options, and process-level environment variables. Each serves a different purpose, and environment variables are not a general fallback for config fields—they need to be understood by category. The CLI executable is named mimo.

#The three roles of environment variables

Environment variables serve three distinct, non-overlapping roles in MiMo Code. For the full variable table, see Environment Variables.

1. Resource location and injection — MIMOCODE_HOME sets the profile root, MIMOCODE_CONFIG / MIMOCODE_CONFIG_DIR / MIMOCODE_CONFIG_CONTENT point directly at config sources, and MIMOCODE_PERMISSION inlines a permission block.
2. Runtime switches — the MIMOCODE_DISABLE_* and MIMOCODE_ENABLE_* families control whether a capability is enabled, with the semantics of "an extra switch on top of config." For example, MIMOCODE_DISABLE_AUTOUPDATE turns off auto-update even if the config says autoupdate: true.
3. Auth and endpoints — MIMOCODE_AUTH_CONTENT / MIMOCODE_CONSOLE_TOKEN / MIMOCODE_SERVER_PASSWORD and friends inject credentials for CI and server mode.

#Precedence for ordinary runtime parameters

The resolution order for non-environment-variable parameters is: command-line options > config file. But a few points first.

• Most CLI flags (--model / --agent / --variant / --prompt / --continue, etc.) apply only to the current prompt's run and are not written back to mimocode.json; the next session still reads the config file values.
• Network flags (--port / --hostname / --mdns / --mdns-domain / --cors) override config.server.* only when actually passed on the command line. Among them, --cors appends to the config CORS list rather than replacing it.
• A few environment variables explicitly override config fields: e.g. MIMOCODE_AUTO_SHARE=true is equivalent to share: "auto", and MIMOCODE_DISABLE_AUTOCOMPACT=true is equivalent to turning off compaction.auto. This "env var overrides config field" case is the exception—see the individual field notes.

#Config files

The location of config files is controlled by MIMOCODE_HOME; when unset, the global config defaults to $XDG_CONFIG_HOME/mimocode/ (equivalent to ~/.config/mimocode/ on macOS and Linux).

MIMOCODE_HOME must be an absolute path (a ~/ prefix is not accepted), otherwise startup errors out. Once set, the following four base directories all move under that path:

File name rules:

• The global directory accepts config.json / mimocode.json / mimocode.jsonc, merged in that order (later overrides earlier).
• The project directory only accepts mimocode.json / mimocode.jsonc, searched from the current directory up to the worktree root, merged layer by layer with parent first, current last. Other names (e.g. opencode.json) are not loaded.
• .mimocode/ and MIMOCODE_CONFIG_DIR likewise use mimocode.json(c).

Merge rules:

• The general merge is a deep merge, recursing per key on objects.
• Arrays are replaced wholesale by default; instructions is the exception, deduplicated and concatenated.
• plugin / mcp entries with the same name are overridden by the later writer (consistent with deep merge). Exception: when the Claude Code compatibility layer injects ~/.claude.json's mcpServers into mcp, it skips any entry whose name already exists in mcp, to avoid overriding the user's explicit config.
• The tools field is translated into derived permission entries, but a user's explicit permission takes precedence.
• theme / keybinds / tui in mimocode.json are silently dropped with a prompt to migrate them to ~/.config/mimocode/tui.json.
• macOS MDM managed preferences (/Library/Managed Preferences/.../ai.opencode.managed.plist) override wholesale on top of all user-layer config (including MIMOCODE_CONFIG_CONTENT), and ordinary users cannot bypass them.

For field definitions, see Config Files.

#Provider credentials

Credentials (API keys, OAuth tokens, etc.) are not stored in mimocode.json; they live in a separate auth file:

• Read by default from $XDG_DATA_HOME/mimocode/auth.json with 0o600 permissions; it moves along with MIMOCODE_HOME when that is set.
• MIMOCODE_AUTH_CONTENT takes a full JSON string as inline credentials, for CI scenarios.
• In the default mimo-only mode (MIMOCODE_MIMO_ONLY=true), provider environment variables such as ANTHROPIC_API_KEY / OPENAI_API_KEY are not read from the shell as a fallback. Only MIMOCODE_MIMO_ONLY=false restores this fallback; setting MIMOCODE_DISABLE_PROVIDER_ENV=false alone has no effect (the flag is always true while mimo-only is true).
• To keep credentials in mimocode.json without exposing them in version control, use the {env:VAR} or {file:path} placeholders (see Config Files · Variable substitution).

#Process-level environment variables

The practical effects of process-level environment variables cluster in the following directions, matching the "three roles" above:

• Resource root and config injection — MIMOCODE_HOME / MIMOCODE_CONFIG / MIMOCODE_CONFIG_DIR / MIMOCODE_CONFIG_CONTENT / MIMOCODE_PERMISSION.
• Runtime switches — MIMOCODE_DISABLE_* / MIMOCODE_ENABLE_* / MIMOCODE_PURE.
• Auth and endpoints — MIMOCODE_AUTH_CONTENT / MIMOCODE_SERVER_PASSWORD / MIMOCODE_SERVER_USERNAME / MIMOCODE_CONSOLE_TOKEN / MIMOCODE_WORKSPACE_ID.
• Diagnostics and internal — MIMOCODE_SHOW_TTFD / MIMOCODE_AUTO_HEAP_SNAPSHOT, etc., not recommended for regular use.

For the full variables, defaults, and semantics, see Environment Variables.

#Command-line options

The table below lists the most common global options, grouped by subcommand, that either interact with config or change the behavior of the current run. For the full list, see Command Line.

The attach subcommand requires a positional argument <url> pointing at the remote server: mimo attach <url> [flags...].

Mutual exclusion and dependencies:

• --continue and --session cannot both specify a new session source; --fork must be used with one of them.
• When --mdns is enabled and neither --hostname is passed nor server.hostname is set in config, hostname defaults to 0.0.0.0; if hostname is specified anywhere, that value is used.
• --share is subject to MIMOCODE_DISABLE_SHARE; this flag has no effect when that is true.
• --dangerously-skip-permissions is only valid under the run subcommand; inside the TUI it is enabled via a slash command.

#Typical scenarios

Switch the profile root for isolated testing.

MIMOCODE_HOME=/tmp/mimo-test mimo

Inline config and credentials in CI without relying on disk files.

MIMOCODE_CONFIG_CONTENT='{"model":"mimo/mimo-v2.5-pro","share":"disabled"}' \
MIMOCODE_AUTH_CONTENT='{"anthropic":{"apiKey":"sk-..."}}' \
  mimo run "Generate release notes"

Skip all permission prompts for this run (run only).

mimo run --dangerously-skip-permissions "Format all TypeScript files"

Temporarily switch model for this run without changing the default.

mimo run -m mimo/mimo-v2.5-pro "Summarize the diff"

Enable basic auth and switch ports for serve.

MIMOCODE_SERVER_USERNAME=alice MIMOCODE_SERVER_PASSWORD=s3cret \
  mimo serve --port 4096

#Deprecated "remote endpoint" name

Historical docs wrote the remote well-known endpoint as .well-known/mimocode. The source actually requests .well-known/opencode; use the latter when setting your own organization defaults.