Configuration reference

Understand settings ownership, local paths and supported runtime overrides.

Mellow offers two complementary ways to configure the app: interactive settings for day-to-day changes and a declarative document for repeatable setup. Use the document to describe intended state, inspect the difference, and apply a deliberate change. Keep passwords, API keys, and consent outside the document.

Begin from your installed build

mellow config export -o mellow-current.yaml
mellow config schema --format yaml
mellow config schema --format json

The exported state and generated schema are the authoritative starting point for that build. They avoid copying a field from a different release or guessing a renamed setting. The YAML schema is useful while editing; JSON Schema is useful for validation and editor tooling.

Save a copy of the current export before changing it. Work on a separate file, make one coherent change, and compare the plan. Configuration exports omit secrets, so a restored provider may still need its credentials supplied through Mellow.

Preview, then apply

mellow config plan mellow-next.yaml
mellow config apply mellow-next.yaml

Planning validates the document and describes its effects. Applying changes the managed state. A high-risk operation can require explicit confirmation: examples include deleting managed items, enabling channel writes, adding an MCP endpoint, or granting screen/browser capabilities.

Use --yes only after reviewing the risk list. Use --prune only when the document is intended to be the complete managed set and removal of absent entries is desired. A partial setup document should not accidentally become a deletion instruction.

After applying, open the affected settings, check the resulting value, exercise the relevant workflow, and relaunch when persistence matters. A successful response establishes that the configuration request was handled; it does not establish that a new credential or external endpoint works.

Separate the layers of configuration

A declarative setting cannot stand in for a missing macOS permission or a user completing an external consent screen. Keep these states explicit in setup automation.

Environment variables you can use

An environment variable in a shell affects processes launched from that environment. It does not automatically reconfigure an already-running GUI app. Stop and relaunch through the intended development launcher when testing startup variables.

The test flags are for isolated development. They intentionally prevent proof of real account credentials and device identity; do not use them to diagnose whether a user's normal Keychain connection works.

Local inference settings

Keep explicit overrides distinct from model defaults. The runtime resolves applicable request and user settings together with bundle generation configuration. An omitted value should not be replaced by an arbitrary example default in your client.

For cache, concurrency, speculative decoding, and memory controls, verify the effective runtime state after the change. Some settings apply on the next model load. Unsupported combinations should surface an explanation; silently ignoring a setting is not a successful configuration.

HTTP configuration interface

These administrative operations are loopback-only. Prefer the CLI unless you need to implement the HTTP document envelope yourself. Do not expose an administrative setup flow through a relay by assuming a cloud login grants local configuration authority.

Troubleshooting configuration drift

If the UI and an export disagree, first confirm the active app installation and data root. If a value persists but behavior does not change, inspect the consuming workflow: provider selection, per-agent override, next-load setting, or host permission may determine the result. Capture the before export, planned diff, after export, and one real request. That evidence is more useful than repeatedly reapplying the same document.