magentic-ui Documentation

Technical Documentation: microsoft/magentic-ui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

MagenticLite is the next generation of Magentic-UI — an agentic application from Microsoft AI Frontiers, redesigned to do more with less. It pairs an on-device-friendly orchestrator model (MagenticBrain) with a specialized browser-use model (Fara) so you can automate real work without depending on frontier-scale compute.

• Built for small models, efficient by design. Strong agentic performance without heavy compute — no frontier-scale models required.
• Works across the browser and your local file system. Web research, form filling, file management — in one workflow.
• Keeps you in the loop and in control. Steer, approve, or take over at any point. MagenticLite stops and checks in before taking critical actions.
• Safe by design. Browser sessions run inside a lightweight VM sandbox (Quicksand) so the agent can't reach the rest of your machine without your say-so.

See it in action Copy Chapter

Click any task below to expand and watch MagenticLite handle it end to end.

Fill expense forms

https://github.com/user-attachments/assets/a982b60d-127e-4310-96e6-9f094dffb7f0

Find prices for recipe ingredients

https://github.com/user-attachments/assets/7ff87917-752f-4e40-b319-8036e08ab8f9

Find and book a restaurant

https://github.com/user-attachments/assets/ee5f967e-ee1b-4554-b329-36b56b595aa4

Organize local files

https://github.com/user-attachments/assets/aff385dd-f856-4db4-8f26-08fd0f940aa4

Quick start Copy Chapter

These steps get you running on macOS or Windows (WSL). Need more detail or a different platform? See the Installation Guide.

1. Install MagenticLite Copy Section

# Create a project directory
mkdir magentic-lite && cd magentic-lite

# Create and activate a virtual environment
uv venv --python=3.12 --seed .venv
source .venv/bin/activate

# Install the latest 0.2.x release from PyPI
uv pip install "magentic_ui>=0.2.0"

2. Run Copy Section

magentic-ui --port 8081

Open http://127.0.0.1:8081/ and follow the in-app onboarding to connect a model endpoint. If you don't have one yet, see the Model Hosting Guide.

Looking for the previous Magentic-UI 0.1 release (optimized to run with frontier models)? It lives on the magentic-ui-0.1 branch.

Documentation Copy Chapter

License Copy Chapter

Microsoft, and any contributors, grant you a license to any code in the repository under the MIT License. See the LICENSE file.

Microsoft, Windows, Microsoft Azure, and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Any use of third-party trademarks or logos are subject to those third-party's policies.

Privacy information can be found at https://go.microsoft.com/fwlink/?LinkId=521839.

Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel, or otherwise.

Overview (`frontend/src/components/ui/README.md`) Copy Section

shadcn/ui Components

This directory contains shadcn/ui primitive components. These are generated code, not a library.

Quick Reference Copy Chapter

Adding a New Component Copy Section

For a full list of shadcn/ui components, see: shadcn/ui Components

cd frontend
pnpm dlx shadcn@latest add <component-name>

# Examples:
pnpm dlx shadcn@latest add dialog
pnpm dlx shadcn@latest add dropdown-menu

The CLI reads components.json and generates the component in this folder.

Should I Modify These Files? Copy Section

Generally, no. Follow this priority order:

1. Use variant and size props — Built-in customization

   tsx Copy

   <Button variant="secondary" size="sm">
     Click
   </Button>

2. Add className for one-off styling — Context-specific overrides

   tsx Copy

   <Button className="rounded-full">Pill Button</Button>

3. Modify index.css design tokens — App-wide style changes

   css Copy

   /* Change primary color for the entire app */
   --primary: var(--color-fuchsia-600);

4. Edit component file — Only when design system itself changes

   • Rare: When Figma design system components are updated
   • Example: Adding a new variant that will be used across the app

Do NOT Copy Section

• Add business logic to these files
• Import app-specific code (stores, hooks, API)
• Create one-off variants for a single use case

The `cn()` Utility Copy Chapter

All components use cn() from @/lib/utils to merge class names:

import { cn } from '@/lib/utils'

// Basic usage - merge multiple classes
<div className={cn('base-class', 'additional-class')} />

// Conditional classes
<div className={cn('base', isActive && 'bg-primary')} />

// Override component defaults via className prop
<Button className="rounded-full" />  // overrides default rounded-md

cn() is a wrapper around clsx + tailwind-merge. It:

• Concatenates class names
• Handles conditionals (false, null, undefined are ignored)
• Resolves Tailwind conflicts — later classes override earlier ones

Design Tokens Copy Chapter

Colors and styles are defined in src/index.css. Components use CSS variables like bg-primary, text-foreground, border-border.

Always Use Semantic Colors Copy Section

// ✅ Good - uses semantic tokens, works with light/dark themes
<div className="bg-card text-card-foreground border-border" />
<Button className="bg-primary text-primary-foreground" />

// ❌ Bad - hardcoded Tailwind colors, breaks theming
<div className="bg-neutral-100 text-neutral-900 border-neutral-300" />

Semantic colors automatically adapt to light/dark mode. Raw Tailwind colors don't.

Token Categories Copy Section

When to Use Extended Tokens Copy Section

If the default --accent causes poor contrast (e.g., text too light on hover background), try --accent-0 through --accent-3:

// Default accent might be too similar to background
<div className="bg-accent">...</div>

// Use accent-2 for better contrast
<div className="bg-accent-2">...</div>

Component Conventions Copy Chapter

Prefer shadcn/ui primitives over custom implementations.

For basic UI elements (Button, Card, Dialog, Tooltip, etc.), always use shadcn/ui components. They provide:

• Consistent styling with our design system
• Built-in accessibility (keyboard nav, ARIA, focus management)
• Radix UI primitives (portals, collision detection)

Only create custom components when shadcn/ui doesn't have what you need.

Button Copy Section

Always use for clickable elements (never plain).

// Icon + Text: use gap-2
<Button className="gap-2 rounded-full">
  <Plus className="size-4" />
  New Session
</Button>

// Icon-only: must have aria-label + Tooltip
<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="secondary" size="icon" aria-label="Settings">
      <Settings className="size-4" />
    </Button>
  </TooltipTrigger>
  <TooltipContent>Settings</TooltipContent>
</Tooltip>

Card Copy Section

For compact/interactive cards, skip CardHeader/CardContent wrappers:

<Card className="hover:bg-card-hover transition-colors">
  <div className="flex flex-col gap-3 p-4">{/* Custom layout */}</div>
</Card>

Resources Copy Chapter

• shadcn/ui Documentation
• Project Coding Guidelines
• Design Tokens in index.css

TRANSPARENCY NOTE (`docs/TRANSPARENCY_NOTE.md`) Copy Section

MagenticLite (aka Magentic 2.0) Transparency Notes

Overview Copy Chapter

MagenticLite (aka Magentic 2.0) is a powerful open-source agentic application that works with you to help you complete tasks across the web browser and your local file system. Built as the successor to Magentic-UI, MagenticLite was optimized to work with small language models (SLMs) — making it leaner, faster, and more accessible without sacrificing capability.

Unlike its predecessor, which required SOTA frontier models to achieve desired performance, MagenticLite delivers strong agentic capabilities at a fraction of the cost and compute, while keeping you in control at critical steps.

Looking for the previous version of Magentic-UI optimized to run with frontier models? It lives on the magentic-ui-0.1.x branch.

What Can MagenticLite Do? Copy Chapter

MagenticLite operates its own browser and can access folders that the user grants it access to, working fluidly across both to complete useful, real-world tasks. It can handle a wide range of tasks — from web research and form filling, to file management, data analysis, and code writing and execution.

Every reasoning trace and action is fully visible to the user. Users can steer the agent at any point, either in natural language or by directly taking control of the browser, ensuring they remain in the driver's seat throughout.

Intended Uses Copy Chapter

MagenticLite is a research prototype best suited to explore, experience, and deploy agentic assistance for tasks that require web navigation and local file system interaction.

MagenticLite should always be used with human supervision.

Examples of tasks it can accomplish:

• Fill online forms and make bookings on your behalf
• Research and analyze information across the browser and your local file system
• Manage and analyze your local file system
• Complete simple coding tasks locally

MagenticLite is being shared with the research community to foster further research on agentic systems that keep people in control. It is intended to be used by domain experts who are independently capable of evaluating the quality of outputs, safety issues, and potential harms before acting on them.

Out-of-Scope Uses Copy Chapter

We do not recommend using MagenticLite in commercial or real-world applications without further testing and development. It is being released for research purposes.

MagenticLite may not work as expected if used with models other than the recommended setup: Fara1.5 for browser use and MagenticBrain for orchestration and coding.

MagenticLite is not well suited for tasks that:

• Rely on audio or video data
• Involve long-duration tasks (e.g., summarizing 100+ papers)
• Require real-time fast actions such as playing online games

MagenticLite should always be used with a human in the loop. It was not designed or evaluated for all possible downstream purposes. Developers should consider its inherent limitations as they select use cases, and evaluate and mitigate for accuracy, safety, and fairness concerns specific to each intended downstream use.

MagenticLite should not be used in:

• Highly regulated domains or high-stakes situations where inaccurate outputs could suggest actions that lead to injury or negatively impact an individual's health, legal, financial, or life opportunities
• High-risk decision making (e.g., in law enforcement, legal, finance, or healthcare)

How to Get Started Copy Chapter

To begin using MagenticLite, follow instructions in the README page or check our installation guide under /docs.

Evaluation Copy Chapter

MagenticLite was evaluated on its ability to solve complex agentic tasks, both in standard benchmark settings and on a custom evaluation dataset designed around priority use cases.

Evaluation Methods Copy Section

Evaluations were driven by hero use cases reflecting real everyday tasks — including form filling, browser research, and file system management. A custom evaluation dataset was built around these scenarios to measure performance on tasks that reflect actual user value, complementing standard benchmarks rather than simply optimizing for them.

Recommended models for evaluation: MagenticLite was developed and tested using Fara1.5 and MagenticBrain as the recommended model configuration. These are the models on which all evaluations and safety testing were conducted. Users may substitute other models, but performance, safety behavior, and benchmark results are not guaranteed outside of the tested configuration.

In addition to quality performance testing, MagenticLite was assessed from a Responsible AI perspective. Based on these results, mitigations were implemented to minimize susceptibility to misuse. See the Risks and Mitigations section below.

Limitations Copy Chapter

• MagenticLite was developed for research and experimental purposes. Further testing and validation are needed before considering its application in commercial or real-world scenarios.
• MagenticLite was designed and tested primarily using the English language. Performance in other languages may vary and should be assessed by someone who is both an expert in the expected outputs and a native speaker of that language.
• Outputs generated by AI may include factual errors, fabrication, or speculation. Users are responsible for assessing the accuracy of generated content. All decisions leveraging outputs of the system should be made with human oversight and not be based solely on system outputs.
• All evaluations and safety testing — including critical point handling, XPIA, and code-harm tests — were conducted on the Fara1.5 + MagenticBrain configuration. Performance and safety behavior have not been tested on other model combinations.
• Users with limited GPU capacity may run only one of the two models, but not all use cases will be unlocked. Users who run MagenticLite without Fara should be aware that critical point detection for browser actions relies on Fara's trained behavior.
• MagenticLite inherits any biases, errors, or omissions produced by the underlying model used.
• There has not been a systematic effort to ensure that all deployment configurations are protected from all security vulnerabilities such as indirect prompt injection attacks.
• MagenticLite plans one step at a time rather than committing to a full upfront plan, making it more adaptive and easier to course-correct — a deliberate design choice for SLM-based orchestration.

A list of tasks and usage patterns that are not well supported is documented in docs/limitations.md.

Best Practices Copy Chapter

MagenticLite is a highly capable agent, proficient at interacting with websites, operating over local files, and writing or executing Python code. Like all LLM-based systems, it can and will make mistakes. To safely operate MagenticLite:

• Always run it within Quicksand, a Python wrapper for QEMU VM that provides strong isolation boundaries and is available as part of this open-source release. Strictly limit its access to only essential resources — avoid exposing unnecessary files, folders, or credentials to the agent.
• Avoid logging into websites through the agent unnecessarily.
• Never share sensitive data you would not confidently send to external providers. MagenticLite shares browser screenshots with model providers, including all data entered on websites within its browser session.
• Ensure careful human oversight: meticulously review proposed actions and monitor progress before giving approval.
• Approach outputs with appropriate skepticism — MagenticLite can hallucinate, misattribute sources, or be misled by deceptive or low-quality online content.

We strongly encourage users to pair MagenticLite with models that support robust Responsible AI mitigations. For reference on responsible AI best practices:

• Announcing new AI safety & Responsible AI features in Azure
• Azure OpenAI Overview
• Azure OpenAI Transparency Note
• OpenAI Usage Policies
• Azure OpenAI Code of Conduct

Users are reminded to be mindful of data privacy concerns and are encouraged to review the privacy policies associated with any models and data storage solutions interfacing with MagenticLite. It is the user's responsibility to ensure that the use of MagenticLite complies with relevant data protection regulations and organizational guidelines.

Risks and Mitigations Copy Chapter

The risk surface spans the files and websites the agents have access to. The two primary risk categories are:

• Data leakage from prompt injection. Untrusted content encountered in the browser or in user-supplied files may attempt to manipulate the agent into exfiltrating data or taking unintended actions. MagenticLite shares browser screenshots with model providers, including any data entered on websites within its session.
• Undesired or destructive actions across the user's local file system, the operated browser, or executed code — including irreversible operations the user did not intend to authorize.

Mitigations Copy Section

MagenticLite mitigates these risks through a layered approach:

• Sandboxed execution environment. All browser sessions and code execution happen inside Quicksand, a Python wrapper around a QEMU VM that provides strong isolation boundaries from the host system. This limits the blast radius of both prompt injection and undesired actions.
• Human intervention at critical points in the browser. Fara's training surfaces actions that warrant user approval (e.g., transactions, irreversible submissions, login flows), pausing for explicit user confirmation before proceeding.
• Code action classification at the MagenticLite harness level. The allow / require_approval / deny tables categorize every tool call and bash command from the Orchestrator model, blocking destructive operations and routing risky ones through user approval.
• User guidance on limiting data exposure. We recommend that users:
  • Grant the agent access to only the folders strictly necessary for the task
  • Avoid logging into websites through the agent unless required
  • Never share sensitive data they would not confidently send to external model providers
  • Use the recommended model configuration (Fara1.5 + MagenticBrain), where critical point detection has been tested

Users who choose to disable Fara, substitute alternative models, or run MagenticLite outside the sandboxed VM forfeit one or more of these mitigations and should evaluate the residual risk for their use case.

How Critical Point Detection Works Copy Section

In Magentic-UI 0.1, critical point detection was handled by prompting the configured frontier model (e.g., GPT-4o) to flag actions that warranted user review. This prompting-based safety layer no longer exists in this release. Instead, critical point detection has been moved closer to where each kind of action originates:

Browser actions → handled by Fara's trained behavior.
The need for human intervention in browser use is rarely black-and-white and contains many gray areas. Rather than rely on post-hoc prompting, we trained Fara on traces that include correctly calibrated critical points, so the model itself learns when to surface an action for user approval. This generalizes better than prompting and avoids the latency overhead of routing each step through a separate large model. Users who do not run Fara should be aware that this safeguard depends on Fara's training and is not provided by MagenticLite itself.

Code and tool actions → handled by the MagenticLite harness.
MagenticBrain works with a discrete set of tools and bash commands, which makes a deterministic, list-based approach well-suited. The harness applies an allow / require_approval / deny classification to every tool call and bash command before execution:

This split — model-level for browser, harness-level for code — reflects the different shapes of the two action spaces: continuous and ambiguous in the browser, discrete and enumerable in code.

Important note for users familiar with Magentic-UI 0.1: Because critical point detection is no longer provided by MagenticLite itself, running this release with a browser-use model other than Fara, or with a coding model that bypasses the harness, will not give you the same safety behavior that was tested and approved in 0.1. We strongly recommend the recommended model configuration described above.

License Copy Chapter

MIT License

Nothing disclosed here, including the Out of Scope Uses section, should be interpreted as or deemed a restriction or modification to the license the code is released under.

Contact Copy Chapter

We welcome feedback and collaboration from our audience. If you have suggestions, questions, or observe unexpected/offensive behavior in our technology, please contact us at [email protected].

If the team receives reports of undesired behavior or identifies issues independently, we will update this repository with appropriate mitigations.

Build From Source (`docs/build-from-source.md`) Copy Section

Build from Source

This guide is for anyone who wants to run MagenticLite from a clone of this
repo — for example to make local changes to the backend or frontend, to test
an unreleased commit, or to dig into the code.

If you only want to run MagenticLite, the released magentic_ui package on
PyPI is what you want — see Installation instead.

Prerequisites Copy Chapter

Platform-level prerequisites (Homebrew / WSL2 / KVM / uv / Python 3.12) are
the same as a regular install — follow the Installation guide
through the macOS or Windows (WSL) prerequisites section, then come
back here.

In addition, building the frontend requires:

• Node.js v24 or later
• pnpm v10+

# Install Node via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24

# Install pnpm
npm install pnpm

Clone the repo Copy Chapter

git clone https://github.com/microsoft/magentic-ui.git
cd magentic-ui

Backend setup Copy Chapter

uv venv --python=3.12 --seed .venv
source .venv/bin/activate
uv sync --all-extras

uv sync installs MagenticLite in editable mode along with all dev
dependencies. The Quicksand VM image is downloaded automatically the first time
you launch magentic-ui; you don't need to run a separate install step for it.

Frontend setup Copy Chapter

The frontend is a Vite + React app under frontend/. Production builds are
written into src/magentic_ui/backend/web/ui/, where the backend serves them as
static files.

cd frontend
pnpm install

You then have two ways to run the UI, depending on what you're working on.

Option 1: Production-style run Copy Section

Build the frontend once into the backend's static directory, then launch the
backend and let it serve the bundle. Use this when you're working only on
backend code.

# from frontend/
pnpm build      # outputs to ../src/magentic_ui/backend/web/ui/
cd ..

magentic-ui --port 8081

Open http://127.0.0.1:8081/. Re-run pnpm build whenever the frontend
changes.

Option 2: Frontend dev mode Copy Section

Run the Vite dev server with hot reload, and run the backend separately. Use
this when you're iterating on the UI.

# Terminal 1 — backend
source .venv/bin/activate
magentic-ui --port 8081

# Terminal 2 — frontend dev server
cd frontend
pnpm dev        # serves at http://localhost:5173

Open http://localhost:5173/. The Vite dev server proxies API and WebSocket
calls to the backend on port 8081.

For UI component conventions, see
frontend/src/components/ui/README.md.

Configuration (`docs/configuration.md`) Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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.

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 Copy Chapter

sandbox.type controls how agent code runs:

sandbox:
  type: quicksand

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

Tool approval Copy Chapter

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

Set the policy in YAML:

harness_config:
  orchestrator:
    approval_policy: require_approval_untrusted

Next steps Copy Chapter

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

Installation (`docs/installation.md`) Copy Section

Installation

This guide walks you through installing MagenticLite. It covers macOS and Windows (WSL); Linux is similar to the Windows/WSL path.

Supported platforms Copy Chapter

Pick the section that matches your machine and follow it end to end. The "Install and run" steps at the bottom apply to both platforms.

Install prerequisites on macOS Copy Chapter

Tested on macOS ARM64 (Apple Silicon).

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# If you just installed Homebrew, add it to your shell PATH
# (Apple Silicon path; for Intel Macs use /usr/local/bin/brew)
eval "$(/opt/homebrew/bin/brew shellenv)"

# Python 3.12+
brew install [email protected]

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # add uv to PATH for this shell

Skip ahead to Install and run MagenticLite.

Install prerequisites on Windows (WSL) Copy Chapter

Tested on Windows 11 x64 with WSL2 + Ubuntu.

1. Install WSL and Ubuntu Copy Section

In PowerShell as Administrator:

wsl --install

Reboot if prompted, then launch Ubuntu — either from the Start menu, or by running wsl (or ubuntu) in a new PowerShell window — and complete the first-time user setup. Every command from here on runs inside the Ubuntu (WSL) shell.

2. Enable KVM Copy Section

sudo usermod -aG kvm $USER

Close and reopen the WSL terminal for the group change to take effect.

KVM gives the Quicksand VM hardware acceleration. Without it the VM falls back to software emulation, which is significantly slower.

3. Install tools Copy Section

# uv (Python package manager) — installed first because we use uv to manage Python
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # add uv to PATH for this shell

# Python 3.12 (managed by uv; the apt python3.12 package isn't available on Ubuntu 22.04)
uv python install 3.12

Install and run MagenticLite Copy Chapter

Once the platform-specific prerequisites are in place, the install + run steps are the same on both platforms.

# Create a project directory
mkdir magentic-lite && cd magentic-lite

# Create and activate a virtual environment
uv venv --python=3.12 --seed .venv
source .venv/bin/activate

# Install the latest 0.2.x release from PyPI
uv pip install "magentic_ui>=0.2.0"

# Run
magentic-ui --port 8081

Then visit http://127.0.0.1:8081/ in your browser.

For subsequent runs:

cd magentic-lite
source .venv/bin/activate
magentic-ui --port 8081

Only one MagenticLite instance can run at a time on the same port (default 8081).

Coming from Magentic-UI 0.1.x? Copy Chapter

If you previously ran a 0.1.x release of Magentic-UI on the same machine, two things to know:

• Pin the version when you install. PyPI still hosts the 0.1.x line under the same magentic_ui package name, so a plain uv pip install magentic_ui may pick up an older release. Pin to a 0.2.x version explicitly:

  bash Copy

  uv pip install "magentic_ui>=0.2.0"

• Use a fresh data directory. MagenticLite (0.2.x) does not migrate the 0.1.x database. To keep the two installs side-by-side, point this run at a different --appdir:

  bash Copy

  magentic-ui --port 8081 --appdir ~/.magentic-lite

  Without --appdir, MagenticLite uses the same default data directory as 1.0, which can lead to confusing state.

A note on running MagenticLite as a shared service Copy Chapter

MagenticLite is designed to be installed and run locally on your own machine by the same person who uses it. We don't recommend hosting it as a shared service for other users:

• Concurrent multi-user sessions weren't a design goal, so the UX degrades when several people share one instance.
• The app exposes host-level capabilities to whoever can reach it — most notably the file-system mounting controls used for browser uploads and downloads. Running it as a multi-user service effectively grants every user of that service the same file-system access as the host account.

If you do choose to host it, treat the resulting URL as you would shell access to the host machine.

Next steps Copy Chapter

• Model Hosting Guide — get a model endpoint to point MagenticLite at.
• Configuration — sandbox, agent mode, and tool approval policies.
• Troubleshooting — common issues and fixes.

Limitations (`docs/limitations.md`) Copy Section

Limitations

MagenticLite is a research prototype. Some things it doesn't handle well today:

• Summarization is limited. Tasks that ask MagenticLite to read a long source and produce a faithful summary often miss important content or oversimplify.
• Long multi-turn conversations degrade. Quality drops as the conversation history grows, especially for tasks that require keeping many earlier details in mind.
• Steering may not always stick. Even when you successfully redirect the browser-use agent (Fara) mid-task, MagenticBrain may ignore your correction once Fara returns and dispatch Fara back to the original sub-task. The agent's overall plan can be stubborn that way.
• Very large files or contexts don't fit. Tasks that require reading or producing very large documents (well beyond a typical chat-sized prompt) will fail or truncate.
• Uploading files inside the browser isn't supported. The browser-use agent cannot complete flows that require attaching a file from your local disk through a webpage's upload control.
• Images aren't supported as task inputs. Any task that hinges on the agent opening an image file you provide (e.g. "describe this picture", "extract text from this screenshot") will not succeed.

If you hit something not on this list and aren't sure whether it's expected, please file an issue.

Model Hosting Guide (`docs/model-hosting-guide.md`) Copy Section

Model Hosting Guide

MagenticLite talks to models through servers that expose an OpenAI-compatible /v1/chat/completions endpoint. To connect one, provide its base URL, typically ending in /v1. You have a few ways to host one:

• Hugging Face Inference Endpoints. Managed GPU hosting, billed per minute. Walked through in Option A below.
• Bring your own GPU. Run the models yourself with vLLM on GPU machines you manage. Walked through in Option B below.
• Microsoft Foundry Managed Compute. Managed GPU hosting on Azure, billed per hour. Walked through in Option C below.

Whichever path you pick, you end up with the same three values to paste into MagenticLite's onboarding (or into Settings → Models): an OpenAI-compatible URL, a model name, and an API key.

Each model needs its own endpoint. MagenticLite uses one model for the orchestrator role and another for browser use. On a managed platform, that means two deployments, each with its own URL and key. With your own GPUs, you run two vLLM servers; this guide uses two single-GPU machines.

Option A: Hugging Face Inference Endpoints Copy Chapter

Prerequisites Copy Section

• A Hugging Face account with a payment method or pre-paid credits.

• A Hugging Face access token from Settings → Access Tokens. Choose Fine-grained and grant at least:

  • Inference → Make calls to your Inference Endpoints
  • Repositories → Read access to contents of all public gated repos you can access

  Save the token — it's shown only once.

A1. Deploy the model Copy Section

You'll repeat this once per model role you want to use (browser use and/or orchestrator).

1. Open the model card on Hugging Face — microsoft/Fara1.5-9B for browser use or microsoft/MagenticBrain for orchestration — and click Deploy → Inference Endpoints (dedicated).

2. The first time you do this, Hugging Face shows an OAuth consent screen for the Inference Endpoints app. Click Authorize. After authorization, the create-endpoint form resets to defaults — re-apply your settings before deploying.

3. Configure the endpoint:

   Field	Value
   Endpoint Name	e.g. fara-15-9b-magentic-lite or magenticbrain-magentic-lite
   Hardware	the form's current Suggested configuration
   Inference Engine	vLLM
   Authentication	Private (default)
   Autoscaling → Scale-to-Zero	15 minutes

   When validated, Hugging Face suggested:

   • Fara: Nvidia L40S ×1 (48 GB, ~$1.80/hr)
   • MagenticBrain: Nvidia RTX PRO 6000 Blackwell ×1 (96 GB, ~$2.75/hr)

   In Advanced Configuration, enter the complete string for your model in the single Container Arguments text field:

   • Fara: --dtype bfloat16 --max-model-len 262144 --limit-mm-per-prompt {"image":10}
   • MagenticBrain: --enable-auto-tool-choice --tool-call-parser hermes --max-model-len 32768

4. Click Create Endpoint.

   The endpoint takes ~5–10 minutes to build (Hugging Face downloads the weights and starts vLLM). Billing starts when the status changes from Initializing to Running.

A2. Connect MagenticLite Copy Section

When the endpoint is Running, copy the Endpoint URL from its overview page and append /v1 when entering it in MagenticLite. Use the URL Hugging Face provides for each deployment; its hostname depends on the cloud provider and region you selected.

Open MagenticLite and fill in the Browser use model card (and/or the Orchestrator card). On first launch this is part of the onboarding flow; if you've already onboarded, find the same fields under Settings → Models.

The endpoint name identifies the deployment and does not determine the Model Name. Use the model ID shown below.

Click Verify & Save. See Verification fails below if you hit an error.

A3. Scale-to-zero and cold starts Copy Section

If you enabled scale-to-zero in step A1, the endpoint automatically scales to zero after the configured idle window (15 minutes in this guide). It stops billing and is shown as Scaled to zero on the Hugging Face dashboard. This differs from manually pausing an endpoint, which requires a manual resume.

The next request to a scaled-to-zero endpoint triggers a cold start: Hugging Face brings a replica back up, which often takes 30–90 seconds and can take several minutes for a larger model. During this window MagenticLite may show an error like "Endpoint returned HTTP 503" on Verify & Save, or the first chat turn may appear to hang. Wait and retry.

Subsequent requests respond at normal speed until the endpoint scales to zero again.

Option B: Bring Your Own GPU with vLLM Copy Chapter

To host models with vLLM, you need to provide your own GPU-equipped Linux machines. This guide uses two single-GPU machines as the example: one for Fara and one for MagenticBrain. For the model-card commands below, plan for at least 48 GB of GPU memory for Fara and 96 GB for MagenticBrain. Hardware needs may change if you adjust the context length or other vLLM options.

B1. Start the model servers Copy Section

On the Fara machine, run the command from the model card:

vllm serve microsoft/Fara1.5-9B \
   --dtype bfloat16 \
   --max-model-len 262144 \
   --limit-mm-per-prompt image=10

On the MagenticBrain machine, run the command from the model card:

vllm serve microsoft/MagenticBrain \
   --enable-auto-tool-choice \
   --tool-call-parser hermes \
   --max-model-len 32768

B2. Connect MagenticLite Copy Section

The default model names are the repository IDs shown below. If you add --served-model-name, use that value instead.

Click Verify & Save.

Option C: Microsoft Foundry Managed Compute Copy Chapter

Prerequisites Copy Section

• An Azure subscription with a valid payment method. Free and trial subscriptions don't work for GPU deployments.
• A hub-based project in Foundry. The newer "Foundry project" type does not support Managed Compute. If you don't have one, create it from the Foundry portal under + New project → Hub-based project. Pick a region with H100 or A100 inventory (East US 2 and Sweden Central are good defaults).
• Quota for enough dedicated vCPUs in the chosen region. Standard_NC24ads_A100_v4 is a good VM SKU for both Fara1.5-9B and MagenticBrain for testing and typical single-user use, and each instance consumes 24 vCPUs from the quota family. In Azure Quotas, select Machine learning, then request Standard NCADSA100v4 Family Cluster Dedicated vCPUs in the same region as your Foundry project. For the usual two-deployment setup with Fara and MagenticBrain running concurrently at instance count 1, request 48 dedicated vCPUs. Larger A100 or H100 SKUs also work if you want extra headroom or have them readily available, but they cost more. Approval can take 24–48 hours.

C1. Deploy the model Copy Section

You'll repeat this once per model role you want to use (browser use and/or orchestrator).

1. Open the model card in Foundry Explore models: Fara1.5-9B for browser use or MagenticBrain-14B for orchestration.

2. On the model card, click Use this model. If Foundry asks you to select a project, choose an existing hub-based project or create a new one. For a new project, keep the default hub unless you already have a shared hub for this work, and pick a region with GPU inventory such as East US 2 or Sweden Central.

   If project creation fails with a Microsoft.Resources/subscriptions/resourcegroups/write authorization error, your account can see the model but cannot create the Azure resource group behind the Foundry project. Use an existing project where you have access, or ask the subscription owner to grant you a role such as Contributor on the subscription or target resource group, then refresh your credentials and try again.

3. Continue to the deployment wizard. If you're presented with purchase options, pick Managed Compute.

4. Configure the deployment:

   Field	Value
   Endpoint name	anything, e.g. fara-15-9b-magentic-lite. Becomes part of the URL.
   Deployment name	anything, e.g. fara1-5-9b-1 or magenticbrain-14b-1. This is for tracking the deployment in Foundry.
   Virtual machine	Standard_NC24ads_A100_v4. Larger A100 or H100 SKUs also work, but they are usually unnecessary for testing.
   Instance count	1. Foundry may default to 3 instances; reduce it to 1 for testing or typical single-user use to avoid unnecessary cost.

   Both Fara and MagenticBrain are served by vLLM under the hood, so the deployed endpoint exposes a fully OpenAI-compatible /v1/chat/completions route — text and vision-language requests both work.

5. Click Deploy.

   Provisioning takes ~15–20 minutes per model: Foundry allocates the VM, pulls the container, and warms up vLLM. Billing starts when the VM is allocated, not when the endpoint reaches Healthy.

C2. Connect MagenticLite Copy Section

For each deployment, open Models + endpoints in your Foundry project and click into the deployment:

• REST endpoint (Details tab): copy the endpoint through /v1, for example https://<endpoint-name>.<region>.inference.ml.azure.com/v1.
• Model ID (deployment details): use the model name segment after /models/, for example Fara1.5-9B or MagenticBrain-14B. Do not use the deployment name here.
• Primary key (Consume tab): the API key Foundry generated for that endpoint.

Open MagenticLite and fill in the Browser use model card (and/or the Orchestrator card). On first launch this is part of the onboarding flow; if you've already onboarded, find the same fields under Settings → Models.

Click Verify & Save. See Verification fails below if you hit an error.

C3. Idle behavior and cost Copy Section

Foundry Managed Compute deployments do not scale to zero. The VM stays allocated and billed by the hour for as long as the deployment exists, whether or not traffic is flowing. An A100 deployment in East US 2 runs roughly $3–4 per hour at list price (H100 is roughly twice that); check the Azure VM pricing page for current rates in your region. Multiply by the number of deployments you keep running.

To stop the meter, delete the deployment from the Models + endpoints page. Redeploying from the catalog later takes the same ~15–20 minutes.

Verification fails Copy Chapter

When you click Verify & Save, MagenticLite sends a probe request to the endpoint:

• During onboarding, a successful verification finishes the onboarding flow and sends you to the sample-tasks page.
• In Settings, the button updates to Connection Verified (with a check icon) once the endpoint responds.

If verification fails, the banner usually pinpoints the problem:

Troubleshooting (`docs/troubleshooting.md`) Copy Section

Troubleshooting

Model endpoint cold starts Copy Chapter

If you're using a managed model endpoint that scales to zero when idle (Hugging Face Inference Endpoints with scale-to-zero, for example), the first call after the endpoint has been idle may take 30–90 seconds while the platform brings a replica back up. During that window you may see:

• a 503 response or a Verify & Save error in MagenticLite's Settings, or
• the first chat turn appearing to hang.

Wait a minute and try again. Subsequent requests respond at normal speed until the endpoint scales to zero again.

See the Model Hosting Guide for the full explanation.

Settings → Models verification fails Copy Chapter

When you click Verify & Save, MagenticLite sends a probe request to the endpoint. Common failures:

Re-check the values against the source you copied them from (the Hugging Face dashboard, the Foundry deployment page, etc.) and try again.

Installation and runtime Copy Chapter

`magentic-ui` command not found Copy Section

Your virtual environment isn't activated. Re-activate it and try again:

deactivate                    # if another env is active
source .venv/bin/activate
magentic-ui --port 8081

Port 8081 already in use Copy Section

Another MagenticLite process is already running on the same port. Stop it, or run on a different port:

magentic-ui --port 8082

Quicksand VM fails to start (Linux/WSL2) Copy Section

• Confirm KVM is available: [ -e /dev/kvm ] && echo ok should print ok.
• Confirm your user is in the kvm group: groups | grep -q kvm && echo ok. If not, run sudo usermod -aG kvm $USER and restart your shell.
• Without KVM the VM falls back to software emulation, which is significantly slower but should still work.

Browser viewer is blank or unresponsive Copy Section

• Make sure the Quicksand VM is healthy (check the MagenticLite logs for quicksand errors).
• Check that any local firewall isn't blocking the noVNC port the app picks for the embedded browser viewer.
• Restart MagenticLite — the browser is recreated on each session.

Coming from Magentic-UI 0.1.x? Copy Chapter

The 0.1.x line of Magentic-UI is still on PyPI under the same magentic_ui package name, and its on-disk data lives in the same default app directory. A few things to be aware of:

`pip install` picks up Magentic-UI 0.1.x instead of MagenticLite Copy Section

A plain uv pip install magentic_ui (no version pin) may resolve to a 0.1.x release. Pin to a 0.2.x version explicitly:

uv pip install "magentic_ui>=0.2.0"

(Adjust the version to whatever 0.2.x release you intend to run.)

MagenticLite reads / writes my old Magentic-UI 0.1.x data Copy Section

MagenticLite (0.2.x) doesn't migrate the 0.1.x database. By default both versions use the same app directory, which can lead to confusing state. To keep them separate, point MagenticLite at a different --appdir:

magentic-ui --port 8081 --appdir ~/.magentic-lite

Still having issues? Copy Chapter

• Re-check the Installation Guide and Configuration.
• Search GitHub Issues for similar problems.
• Open a new issue and include:
  1. A detailed description of your problem
  2. Information about your system (OS, hardware acceleration support, MagenticLite version)
  3. Steps to reproduce the issue

--- METRICS ---

• Files Extracted: 9
• Estimated Token Budget: ~15333 tokens
• Canonical Reference: https://codewiki.google/github.com/microsoft/magentic-ui