microsoft--magentic-ui/docs/configuration.md

Configuration

For most users, the Settings panel inside the app is all you need. It walks you through model endpoints during the first-launch onboarding flow, and lets you change everything later from Settings → Models (and the other Settings tabs).

If you'd rather use a YAML file — for example to share a setup across machines or check it into source control — the same options are also exposed via config.yaml. The repo ships a config.yaml.example at the project root that you can copy as a starting point:

cp config.yaml.example config.yaml
# then edit config.yaml to taste, and pass it on launch:
magentic-ui --port 8081 --config config.yaml

Each option below shows both the YAML key and (where applicable) the equivalent place in the UI.

How configuration is stored

MagenticLite keeps your effective configuration in a local database, not in the YAML file. There are three ways that database can be populated, and the rule is simple — whichever source wrote last wins, and the result persists across restarts:

• Onboarding UI — runs once on first launch and writes your answers to the database.
• Settings UI — change anything at any time; the new values overwrite the database immediately.
• YAML file via --config — at startup, MagenticLite reads config.yaml and merges it into the database (only fields you explicitly set are overwritten; the rest are left alone). This means starting with --config every time effectively pins those YAML fields back to your file values on every launch, regardless of what the UI changed in between.

A handful of Settings → General options — the display preferences like theme, "show reasoning details", "show tool call details" — are saved to your browser's local storage instead of the backend database. They're per-browser, not per-installation, and they don't show up in config.yaml. Other items in the same panel (e.g. agent step limits) do write to the database like the rest of Settings.

magentic-ui --port 8081 --config config.yaml

To start fresh — clear the saved model endpoints and re-run the onboarding flow — pass --reset-config:

magentic-ui --port 8081 --reset-config

This only clears the model endpoints (orchestrator and browser-use); other configuration (sandbox, agent mode, tool approval) is preserved.

You can combine the two: --reset-config first clears the model endpoints, then --config (if also passed) seeds them from your YAML file.

Model clients

model_client_configs tells MagenticLite which model serves which agent role. There are two roles:

• orchestrator — used in the all and omniagent_only agent modes.
• web_surfer — used in the all and websurfer_only agent modes.

Each entry is an OpenAI-compatible client config — any server that speaks /v1/chat/completions (vLLM, an OpenAI-compatible managed endpoint, your own gateway, …) will work. The full set of fields:

model_client_configs:
  orchestrator:
    provider: OpenAIChatCompletionClient
    config:
      model: <model id the server expects>
      base_url: <https://your-endpoint/v1>
      api_key: <bearer token; leave as a placeholder if your server requires none>
      max_retries: 5
      model_info:
        vision: false
        function_calling: false
        json_output: true
        family: unknown
        structured_output: false
        multiple_system_messages: false

  web_surfer:
    provider: OpenAIChatCompletionClient
    config:
      model: <model id the server expects>
      base_url: <https://your-endpoint/v1>
      api_key: <bearer token>
      max_retries: 5
      model_info:
        vision: true # browser-use models are vision-language
        function_calling: false
        json_output: true
        family: unknown
        structured_output: false
        multiple_system_messages: false

Notes:

• model_info describes the capabilities of the model behind the endpoint. The values shown above are the ones MagenticLite has been tested with for the orchestrator (text-only) and browser-use (vision) roles; use them as-is unless you have a reason to differ for your specific model.
• MagenticLite is tuned for the recommended models (MagenticBrain for the orchestrator, Fara for browser use). Pointing the same fields at a different model will probably work, but expect to tweak prompts and run your own evals; the orchestrator and browser-use code paths are not generic across arbitrary models.
• Azure OpenAI is supported via config.yaml only (the in-app Settings UI doesn't expose it yet): set provider: AzureOpenAIChatCompletionClient and use Azure-specific keys (azure_endpoint, azure_deployment, api_version, azure_ad_token_provider) under config. See config.yaml.example for a worked example.
• If you don't have an endpoint to point at yet, see the Model Hosting Guide for one end-to-end way to stand one up.

Agent mode

agent_mode controls which agents are active. It can also be changed in Settings → Models without restarting. The three modes let you trade capability for setup cost — you can run with both agents, or with only one of them if that's all your task needs.

Mode	Description
all	Orchestrator + Browser use — capable of both local tasks and web browsing (default)
omniagent_only	Orchestrator only — local tasks only; only model_client_configs.orchestrator required
websurfer_only	Browser use only — web browsing tasks only; only model_client_configs.web_surfer required

Which mode to pick:

• all is the default and gives you the full product. You need both an orchestrator endpoint and a browser-use endpoint.
• omniagent_only is useful if you only want local file / code-execution work and don't have a browser-use endpoint to point at. The agent can't use web browser.
• websurfer_only is useful if you only want web automation and don't have an orchestrator endpoint to point at. The agent can't read or write local files.

agent_mode: all

Sandbox

sandbox.type controls how agent code runs:

Type	Description
quicksand	Lightweight QEMU VM with browser isolation (recommended)
null	No isolation — agent runs on host directly (dev/testing only)

sandbox:
  type: quicksand

See Quicksand browser architecture for the technical details and environment variables.

Tool approval

MagenticLite's safety harness prompts the user before executing potentially dangerous tool calls. Three policies are available:

Policy	Behavior
auto_approve	Execute all tool calls without prompting (eval / trusted setups only)
require_approval_untrusted	Prompt before tool calls deemed untrusted; auto-approve read-only (default)
require_approval_all	Prompt before every tool call

Set the policy in YAML:

harness_config:
  orchestrator:
    approval_policy: require_approval_untrusted

Next steps

• Model Hosting Guide — stand up a model endpoint to point model_client_configs at.
• Troubleshooting — what to do when something doesn't work.