# Technical Documentation: microsoft/magentic-ui
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/microsoft/magentic-ui)
### Overview (`README.md`)
Big tasks. Small models.
---
**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](https://aka.ms/MagenticBrain-foundry)) with a specialized browser-use model ([Fara](https://aka.ms/fara-foundry)) 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](https://microsoft.github.io/quicksand/)) so the agent can't reach the rest of your machine without your say-so.
## See it in action
Click any task below to expand and watch MagenticLite handle it end to end.
Fill expense forms
Find prices for recipe ingredients
Find and book a restaurant
Organize local files
## Quick start
These steps get you running on macOS or Windows (WSL). Need more detail or a different platform? See the [Installation Guide](./docs/installation.md).
### 1. Install MagenticLite
```bash
# 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
```bash
magentic-ui --port 8081
```
Open .
Any use of third-party trademarks or logos are subject to those third-party's policies.
Privacy information can be found at .
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`)
# shadcn/ui Components
This directory contains **shadcn/ui** primitive components. These are **generated code**, not a library.
## Quick Reference
### Adding a New Component
For a full list of shadcn/ui components, see: [shadcn/ui Components](https://ui.shadcn.com/docs/components)
```bash
cd frontend
pnpm dlx shadcn@latest add
# 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?
**Generally, no.** Follow this priority order:
1. **Use `variant` and `size` props** — Built-in customization
```tsx
Click
```
2. **Add `className` for one-off styling** — Context-specific overrides
```tsx
Pill Button
```
3. **Modify `index.css` design tokens** — App-wide style changes
```css
/* 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
- 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
All components use `cn()` from `@/lib/utils` to merge class names:
```tsx
import { cn } from '@/lib/utils'
// Basic usage - merge multiple classes
// Conditional classes
// Override component defaults via className prop
```
Semantic colors automatically adapt to light/dark mode. Raw Tailwind colors don't.
### Token Categories
| Category | Example | Use Case |
| ------------ | ----------------------------------- | ------------------------------------- |
| **General** | `--primary`, `--background` | Default choice for most cases |
| **Specific** | `--card`, `--sidebar`, `--popover` | Use when inside that component type |
| **Extended** | `--accent-0` to `--accent-3` | When General tokens have low contrast |
| **Status** | `--status-active`, `--status-error` | Session/task status indicators |
### When to Use Extended Tokens
If the default `--accent` causes poor contrast (e.g., text too light on hover background), try `--accent-0` through `--accent-3`:
```tsx
// Default accent might be too similar to background
...
// Use accent-2 for better contrast
...
```
---
## Component Conventions
**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
Always use `` for clickable elements (never plain ``).
```tsx
// Icon + Text: use gap-2
// Icon-only: must have aria-label + Tooltip
Settings
```
### Card
For compact/interactive cards, skip `CardHeader`/`CardContent` wrappers:
```tsx
{/* Custom layout */}
```
---
## Resources
- [shadcn/ui Documentation](https://ui.shadcn.com)
- [Project Coding Guidelines](/.github/frontend/docs/frontend-coding-guidelines.md)
- [Design Tokens in index.css](../../../index.css)
---
### TRANSPARENCY NOTE (`docs/TRANSPARENCY_NOTE.md`)
# MagenticLite (aka Magentic 2.0) Transparency Notes
## Overview
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](https://www.microsoft.com/en-us/research/publication/magentic-ui-report/), 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?
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
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
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
To begin using MagenticLite, follow instructions in the README page or check our installation guide under `/docs`.
---
## Evaluation
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
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](#risks-and-mitigations) section below.
---
## Limitations
- 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
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](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/announcing-new-ai-safety-amp-responsible-ai-features-in-azure/ba-p/3983686)
- [Azure OpenAI Overview](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/overview)
- [Azure OpenAI Transparency Note](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/transparency-note)
- [OpenAI Usage Policies](https://openai.com/policies/usage-policies)
- [Azure OpenAI Code of Conduct](https://learn.microsoft.com/en-us/legal/cognitive-services/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
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
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
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:
| Classification | Description |
|---|---|
| **Allow** | Low-risk, reversible actions execute automatically (e.g., reading a file, listing a directory) |
| **Require approval** | Actions with potential side effects pause and prompt the user for explicit approval before running |
| **Deny** | Destructive or irreversible actions (e.g., recursive deletes outside the working folder, certain network operations) are blocked outright |
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
**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
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 [magui@service.microsoft.com](mailto:magui@service.microsoft.com).
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`)
# 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](./installation.md) instead.
## Prerequisites
Platform-level prerequisites (Homebrew / WSL2 / KVM / `uv` / Python 3.12) are
the same as a regular install — follow the [Installation guide](./installation.md#supported-platforms)
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+**
```bash
# 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
```bash
git clone https://github.com/microsoft/magentic-ui.git
cd magentic-ui
```
## Backend setup
```bash
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
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.
```bash
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
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.
```bash
# from frontend/
pnpm build # outputs to ../src/magentic_ui/backend/web/ui/
cd ..
magentic-ui --port 8081
```
Open
base_url:
api_key:
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:
base_url:
api_key:
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](https://aka.ms/MagenticBrain-foundry) for the orchestrator, [Fara](https://aka.ms/fara-foundry) 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`](../config.yaml.example) for a worked example.
- If you don't have an endpoint to point at yet, see the [Model Hosting Guide](./model-hosting-guide.md) 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.
```yaml
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) |
```yaml
sandbox:
type: quicksand
```
See [Quicksand browser architecture](./dev/quicksand-browser-architecture.md) 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:
```yaml
harness_config:
orchestrator:
approval_policy: require_approval_untrusted
```
## Next steps
- [Model Hosting Guide](./model-hosting-guide.md) — stand up a model endpoint to point `model_client_configs` at.
- [Troubleshooting](./troubleshooting.md) — what to do when something doesn't work.
---
### Installation (`docs/installation.md`)
# Installation
This guide walks you through installing MagenticLite. It covers macOS and Windows (WSL); Linux is similar to the Windows/WSL path.
## Supported platforms
| Platform | Status | Notes |
| ------------------ | -------------------------------- | ------------------------------------------------------------------ |
| macOS ARM64 | ✅ tested | Apple Silicon. |
| Windows x64 + WSL2 | ✅ tested | Run everything inside the Ubuntu shell. Requires KVM enabled. |
| Linux x64 (native) | ⚠️ untested but expected to work | Same path as WSL2 minus the `wsl --install` step. |
| Windows ARM64 | ❌ not supported | Not currently supported. Support may be added in a future release. |
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
Tested on macOS ARM64 (Apple Silicon).
```bash
# 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 python@3.12
# 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-and-run-magenticlite).
## Install prerequisites on Windows (WSL)
Tested on Windows 11 x64 with WSL2 + Ubuntu.
### 1. Install WSL and Ubuntu
In **PowerShell as Administrator**:
```powershell
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
```bash
sudo usermod -aG kvm $USER
```
Close and reopen the WSL terminal for the group change to take effect.
KVM gives the [Quicksand](https://microsoft.github.io/quicksand/) VM hardware acceleration. Without it the VM falls back to software emulation, which is significantly slower.
### 3. Install tools
```bash
# 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
Once the platform-specific prerequisites are in place, the install + run steps are the same on both platforms.
```bash
# 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 :8000/v1` | `http://:8000/v1` |
| Model Name | `microsoft/Fara1.5-9B` | `microsoft/MagenticBrain` |
| API Key | empty unless the server uses `--api-key` | empty unless the server uses `--api-key` |
Click **Verify & Save**.
---
## Option C: Microsoft Foundry Managed Compute
### Prerequisites
- An [Azure subscription](https://azure.microsoft.com/free/) 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](https://ai.azure.com/) 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](https://aka.ms/fara-foundry) and [MagenticBrain](https://aka.ms/MagenticBrain-foundry) for testing and typical single-user use, and each instance consumes 24 vCPUs from the quota family. In [Azure Quotas](https://portal.azure.com/#view/Microsoft_Azure_Capacity/QuotaMenuBlade/~/overview), 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
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](https://ai.azure.com/explore/models): [Fara1.5-9B](https://aka.ms/fara-foundry) for browser use or [MagenticBrain-14B](https://aka.ms/MagenticBrain-foundry) 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
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://..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**.
| Field | Browser use model (Fara) | Orchestrator model (MagenticBrain) |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------- |
| Endpoint URL | `https://..inference.ml.azure.com/v1` | `https://..inference.ml.azure.com/v1` |
| Model Name | `Fara1.5-9B` | `MagenticBrain-14B` |
| API Key | the primary key from the Fara endpoint's Consume tab | the primary key from the MagenticBrain endpoint's Consume tab |
Click **Verify & Save**. See [Verification fails](#verification-fails) below if you hit an error.
### C3. Idle behavior and cost
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](https://azure.microsoft.com/pricing/details/virtual-machines/linux/) 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
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:
| Symptom (banner) | Likely cause |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Endpoint returned HTTP 401` or `403` | API Key field is empty or wrong (different endpoints return one or the other for the same problem) |
| `Endpoint returned HTTP 503` on the first attempt | Cold start (Hugging Face Inference Endpoints only) — see [§A3](#a3-scale-to-zero-and-cold-starts) above |
| `Connection refused — is the server running?` or other network errors | Endpoint URL is wrong (typo in the host, missing `https://`, VPN/firewall issue) |
---
### Troubleshooting (`docs/troubleshooting.md`)
# Troubleshooting
## Model endpoint cold starts
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](./model-hosting-guide.md#a3-scale-to-zero-and-cold-starts) for the full explanation.
## Settings → Models verification fails
When you click **Verify & Save**, MagenticLite sends a probe request to the endpoint. Common failures:
| Symptom (banner) | Likely cause |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `Endpoint returned HTTP 401` or `403` | API Key field is empty or wrong (different endpoints return one or the other for the same problem) |
| `Endpoint returned HTTP 503` on the first attempt | Cold start — see the section above; wait a minute and click Verify again |
| `Connection refused — is the server running?` or other network errors | Endpoint URL is wrong (typo in the host, missing `https://`, VPN/firewall issue) |
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
### `magentic-ui` command not found
Your virtual environment isn't activated. Re-activate it and try again:
```bash
deactivate # if another env is active
source .venv/bin/activate
magentic-ui --port 8081
```
### Port 8081 already in use
Another MagenticLite process is already running on the same port. Stop it, or run on a different port:
```bash
magentic-ui --port 8082
```
### Quicksand VM fails to start (Linux/WSL2)
- 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
- 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?
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
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:
```bash
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
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`:
```bash
magentic-ui --port 8081 --appdir ~/.magentic-lite
```
## Still having issues?
- Re-check the [Installation Guide](./installation.md) and [Configuration](./configuration.md).
- Search [GitHub Issues](https://github.com/microsoft/magentic-ui/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
