### Initial Magentic UI Installation and Run

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Sets up a project directory, creates and activates a virtual environment using Python 3.12, installs Magentic UI from PyPI, and starts the application on port 8081.

```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
```

--------------------------------

### Copy Example Config and Launch

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Copy the example configuration file and then launch the application with a specified configuration file and port.

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

--------------------------------

### Install Node.js and pnpm

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/build-from-source.md

Installs Node.js version 24 using nvm and globally installs pnpm. Ensure Node.js v24+ and pnpm v10+ are met.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 24

# Install pnpm
npm install -g pnpm
```

--------------------------------

### Install WSL and Ubuntu on Windows

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Run this command in PowerShell as Administrator to install the Windows Subsystem for Linux and the Ubuntu distribution.

```powershell
wsl --install
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/build-from-source.md

Navigates into the frontend directory and installs project dependencies using pnpm. This is required before building or running the frontend.

```bash
cd frontend
pnpm install
```

--------------------------------

### Install Magentic UI

Source: https://github.com/microsoft/magentic-ui/blob/main/README.md

Follow these commands to create a project directory, set up a virtual environment, and install the Magentic UI package.

```bash
mkdir magentic-lite && cd magentic-lite

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

uv pip install "magentic_ui>=0.2.0"
```

--------------------------------

### Install uv Python Package Manager

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Installs the uv package manager using a curl script. It's recommended to install uv first as it manages Python versions.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env  # add uv to PATH for this shell
```

--------------------------------

### Set up Magentic UI Backend

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/build-from-source.md

Creates a Python virtual environment using `uv`, activates it, and installs backend dependencies in editable mode. This prepares the backend for development.

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

--------------------------------

### Launch with Specific Port and Config

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Start Magentic UI, specifying the port and a configuration file.

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

--------------------------------

### Subsequent Magentic UI Runs

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Commands to activate the virtual environment and run Magentic UI for subsequent sessions after the initial setup.

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

--------------------------------

### Install Magentic UI Version 0.2.x or Higher

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/troubleshooting.md

To avoid picking up older 0.1.x releases when installing Magentic UI, explicitly pin to a 0.2.x version or higher using the version specifier in your installation command.

```bash
uv pip install "magentic_ui>=0.2.0"
```

--------------------------------

### Install Homebrew on macOS

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Installs Homebrew package manager using a script. Ensure Homebrew is added to your shell PATH.

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

--------------------------------

### Run Magentic UI

Source: https://github.com/microsoft/magentic-ui/blob/main/README.md

Execute this command to start the Magentic UI application. You can then access it via your web browser.

```bash
magentic-ui --port 8081
```

--------------------------------

### Install uv package manager on macOS

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Installs the uv Python package manager using a script and adds it to the PATH for the current shell session.

```bash
# 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
```

--------------------------------

### Install Python 3.12 with uv

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Installs Python version 3.12 using the uv package manager. This is useful when the system's default Python or apt package is not the desired version.

```bash
uv python install 3.12
```

--------------------------------

### Install Python 3.12 on macOS

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Installs Python version 3.12 using Homebrew. Ensure you have a compatible Python version for MagenticLite.

```bash
# Python 3.12+
brew install python@3.12
```

--------------------------------

### Run Magentic Lite with a Separate App Directory

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/troubleshooting.md

To prevent Magentic Lite (0.2.x) from interfering with or reading data from an older Magentic UI 0.1.x installation, specify a different application directory using the --appdir flag.

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

--------------------------------

### Production-style Frontend Build and Backend Run

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/build-from-source.md

Builds the frontend for production, outputs it to the backend's static directory, and then launches the backend server. Use this when focusing on backend changes.

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

magentic-ui --port 8081
```

--------------------------------

### Set Sandbox Type to Quicksand

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Configures the sandbox to use lightweight QEMU VM with browser isolation. This is the recommended type for security.

```yaml
sandbox:
  type: quicksand
```

--------------------------------

### Frontend Development Mode

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/build-from-source.md

Runs the backend server in one terminal and the Vite development server for the frontend in another. This enables hot-reloading for UI development.

```bash
# 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
```

--------------------------------

### Configure Orchestrator and Web Surfer Model Clients

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Define configurations for both the orchestrator and web surfer roles. Ensure 'model_info' accurately reflects the capabilities of your chosen model endpoint.

```yaml
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

```

--------------------------------

### Launch with Configuration Reset

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Launch Magentic UI and reset its configuration, clearing saved model endpoints and re-running the onboarding flow.

```bash
magentic-ui --port 8081 --reset-config
```

--------------------------------

### Initialize Dark Mode from Local Storage

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/index.html

This code runs immediately to apply dark mode. It reads the 'ui-storage' from localStorage, checks for a 'darkMode' state, and falls back to the system's preferred color scheme if no preference is found. The 'dark' class is added to the document element if dark mode is enabled.

```javascript
MagenticLite // Apply dark mode before first paint to prevent FOUC. // Reads from Zustand persist storage (ui-storage). try { var s = JSON.parse(localStorage.getItem('ui-storage') || '{}'); var dark = s.state && s.state.darkMode; if (dark === undefined) dark = window.matchMedia('(prefers-color-scheme: dark)').matches; if (dark) document.documentElement.classList.add('dark'); } catch (e) {}
```

--------------------------------

### Clone Magentic UI Repository

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/build-from-source.md

Clones the Magentic UI repository and navigates into the project directory. This is the first step to building from source.

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

--------------------------------

### Add a New shadcn/ui Component

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Use the shadcn CLI to add new components to the project. This command reads `components.json` and generates the component files.

```bash
pnpm dlx shadcn@latest add <component-name>
```

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

--------------------------------

### Enable KVM in WSL

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Add the current user to the KVM group within the Ubuntu (WSL) shell. Close and reopen the terminal for changes to take effect.

```bash
sudo usermod -aG kvm $USER
```

--------------------------------

### Add Homebrew to PATH on macOS (Apple Silicon)

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/installation.md

Configures the shell environment to include Homebrew in the PATH for Apple Silicon Macs. For Intel Macs, the path is different.

```bash
# 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)"
```

--------------------------------

### Activate Virtual Environment and Run Magentic UI

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/troubleshooting.md

If the 'magentic-ui' command is not found, ensure your virtual environment is activated. This snippet shows how to deactivate any other active environment, activate the correct one, and then run Magentic UI on a specific port.

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

--------------------------------

### Set Agent Mode to All

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Configures the agent to use both orchestrator and browser capabilities. This is the default mode.

```yaml
agent_mode: all
```

--------------------------------

### Basic Usage of cn() Utility

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Merge multiple class names using the `cn()` utility from `@/lib/utils` for basic styling.

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

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

--------------------------------

### Run Local CI Checks

Source: https://github.com/microsoft/magentic-ui/blob/main/CONTRIBUTING.md

Execute all continuous integration checks locally before submitting code changes. This ensures your code adheres to project standards.

```bash
poe check
```

--------------------------------

### Using Semantic Colors for Theming

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Employ semantic color tokens (e.g., `bg-card`, `text-foreground`) for styles that adapt to light/dark themes. Avoid hardcoded Tailwind colors.

```tsx
// ✅ 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" />
```

--------------------------------

### MagenticLite Browser Model Configuration

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/model-hosting-guide.md

Configure the 'Browser use model' in MagenticLite with your Foundry deployment's Endpoint URL, Model Name, and API Key.

```text
Endpoint URL: https://<fara-endpoint>.<region>.inference.ml.azure.com/v1
Model Name: Fara1.5-9B
API Key: the primary key from the Fara endpoint's Consume tab
```

--------------------------------

### Button with Icon and Text

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Construct a Button component that includes both an icon and text, using `gap-2` for spacing and applying a full rounded style.

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

--------------------------------

### Using Extended Accent Tokens for Contrast

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

When default accent colors provide insufficient contrast, utilize extended tokens like `--accent-0` to `--accent-3` for better readability.

```tsx
// 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>
```

--------------------------------

### Set Tool Approval Policy in YAML

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/configuration.md

Configure the tool approval policy for the safety harness. Use `require_approval_untrusted` for the default behavior, which prompts for untrusted tool calls while auto-approving read-only ones.

```yaml
harness_config:
  orchestrator:
    approval_policy: require_approval_untrusted
```

--------------------------------

### Customize Button with Variant and Size Props

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Utilize the `variant` and `size` props for built-in customization of the Button component.

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

--------------------------------

### Custom Card Layout

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Create a Card component with a custom internal layout, skipping the default `CardHeader` and `CardContent` wrappers. Apply hover effects and transitions.

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

--------------------------------

### Conditional Classes with cn()

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Apply conditional class names based on state using the `cn()` utility. It handles boolean logic for class application.

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

--------------------------------

### Run Magentic UI on a Different Port

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/troubleshooting.md

If port 8081 is already in use by another MagenticLite process, you can run the application on an alternative port by specifying it with the --port flag.

```bash
magentic-ui --port 8082
```

--------------------------------

### MagenticLite Orchestrator Model Configuration

Source: https://github.com/microsoft/magentic-ui/blob/main/docs/model-hosting-guide.md

Configure the 'Orchestrator model' in MagenticLite with your Foundry deployment's Endpoint URL, Model Name, and API Key.

```text
Endpoint URL: https://<brain-endpoint>.<region>.inference.ml.azure.com/v1
Model Name: MagenticBrain-14B
API Key: the primary key from the MagenticBrain endpoint's Consume tab
```

--------------------------------

### Icon-Only Button with Accessibility Features

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Implement an icon-only Button, ensuring accessibility with `aria-label` and providing context via a Tooltip. Use the `secondary` variant and `icon` size.

```tsx
// 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>
```

--------------------------------

### Modify Design Tokens for App-wide Styles

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Change design tokens in `index.css` for app-wide style modifications, such as altering the primary color.

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

--------------------------------

### Override Component Defaults with className and cn()

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Use the `className` prop with `cn()` to override default component styles, such as button rounding.

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

--------------------------------

### Override Button Styling with className

Source: https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/ui/README.md

Apply one-off styling overrides to the Button component using the `className` prop for context-specific adjustments.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.