Playwright-Headless-Browser.../docs/Running-in-Podman-Desktop-a...

18 KiB

Install WebAccess.MCP, Podman Desktop, and LM Studio on a New Windows PC

This guide is for a person starting with a Windows computer that does not yet have Podman Desktop, LM Studio, or WebAccess.MCP installed.

PowerShell privilege labels in this guide mean:

  • PowerShell (Standard user): open PowerShell normally.
  • PowerShell (Admin): right-click PowerShell and select Run as administrator.

Use standard-user PowerShell unless a step is explicitly labeled PowerShell (Admin).

For a shorter operations-only guide that assumes Podman and the repository are already installed, see docs\Standing-Up-the-Podman-Compose-Stack.md.

For a focused, step-by-step LM Studio MCP configuration guide, see docs\Adding-WebAccess-MCP-to-LM-Studio.md.

It creates one predictable AI workspace on a drive of your choice:

<drive>:\ai\
    llm\
        models\                 LM Studio model files
    mcp\
        WebAccess.MCP\          This MCP server and its deployment files

For example, if D: has enough free space:

D:\ai\llm\models
D:\ai\mcp\WebAccess.MCP

The examples below use D:. Substitute another local drive everywhere if needed. Use the same drive consistently.

Podman Desktop and LM Studio are normal Windows applications, so their executables and application settings are installed in Windows-managed locations. Podman also stores container images and volumes inside its managed Linux virtual machine. The model files, MCP source, and deployment configuration are organized beneath <drive>:\ai.

What This Installation Provides

Podman Compose runs three containers:

  • webaccess: the .NET 10 MCP server, Playwright, and headless Chromium.
  • searxng: the dedicated search service used by web_search.
  • postgres: durable page-cache storage.

LM Studio connects to WebAccess.MCP through Streamable HTTP at:

http://127.0.0.1:28081/mcp

SearXNG is available for local diagnostics at:

http://127.0.0.1:28080/

Both ports bind only to the local computer, not to the LAN.

Before You Begin

You need:

  • 64-bit Windows 10 build 19043 or later, or Windows 11.
  • Administrator access for enabling WSL 2.
  • Hardware virtualization enabled in the computer's BIOS or UEFI.
  • At least 6 GB of RAM available to the Podman machine. More RAM is strongly recommended because LM Studio must run a model at the same time.
  • Enough free disk space for Podman images and one or more LLMs. Models commonly consume several to tens of gigabytes each.
  • Internet access during installation, image building, and model download.
  • A trusted copy of the WebAccess.MCP repository.

The optional integration TestRig also requires the .NET 10 SDK. It is not required for normal use because WebAccess.MCP builds inside a container.

1. Choose the AI Drive and Create the Folder Layout

Choose a local drive with enough free space. Avoid a network share, removable drive, OneDrive, or another synchronized folder.

PowerShell (Standard user)

$AiDrive = "D:"
$AiRoot = Join-Path $AiDrive "ai"

New-Item -ItemType Directory -Force -Path `
    (Join-Path $AiRoot "llm\models"), `
    (Join-Path $AiRoot "mcp")

Verify the layout:

Get-ChildItem $AiRoot -Recurse

Keep $AiRoot set in this PowerShell window while completing the installation. In a new PowerShell window, set it again:

$AiRoot = "D:\ai"

2. Install WSL 2

Podman uses a small Linux virtual machine on Windows. WSL 2 is the recommended provider.

PowerShell (Admin)

wsl --install --no-distribution

Restart Windows if prompted. After restarting, open PowerShell and verify WSL:

wsl --status

If WSL installation fails, confirm that virtualization is enabled in BIOS/UEFI and that Windows is fully updated before continuing.

3. Install and Configure Podman Desktop

Install the application

Use either method below.

Option A: Windows Package Manager

Open PowerShell and run:

winget install --exact --id RedHat.Podman-Desktop

Option B: Windows installer

  1. Download Podman Desktop from podman-desktop.io/downloads.
  2. Run the downloaded installer.
  3. Choose whether to install it for the current user or all users.
  4. Complete the installer and start Podman Desktop.

Complete Podman Desktop onboarding

In Podman Desktop:

  1. Select Start Onboarding.
  2. Allow Podman Desktop to install the Podman engine.
  3. Keep WSL 2 selected as the machine provider.
  4. Create the Podman machine when prompted.
  5. Install the Compose CLI when prompted.
  6. Complete onboarding and open the dashboard.

If onboarding was previously skipped:

  1. Open Settings > Resources.
  2. In the Podman tile, select Setup Podman.
  3. Create and start a WSL-based Podman machine.
  4. In the Compose tile, select Setup.

The official Podman Desktop minimum is 6 GB of RAM for its machine. If the computer has sufficient memory, assign more resources in Podman Desktop so Chromium, PostgreSQL, and SearXNG can run comfortably alongside LM Studio.

Open a new PowerShell window and verify both components:

podman info
podman compose version

Do not continue until both commands succeed. If podman info cannot connect, open Podman Desktop and start its Podman machine.

4. Install LM Studio and Set Its Model Folder

  1. Download LM Studio for Windows from lmstudio.ai/download.

  2. Run the installer and start LM Studio.

  3. Complete the initial setup.

  4. Open My Models in LM Studio.

  5. Use the model-directory control to change the models directory to:

    D:\ai\llm\models
    

LM Studio may create organization and model subdirectories beneath this folder. Do not manually flatten those directories.

WebAccess.MCP requires LM Studio 0.3.17 or later. Check the installed version in LM Studio and install any offered update before configuring MCP.

5. Put WebAccess.MCP Under the AI Folder

The final repository location must be:

D:\ai\mcp\WebAccess.MCP

Use one of the following methods.

Option A: Copy a supplied folder

If WebAccess.MCP was supplied as a folder, copy the entire folder into:

D:\ai\mcp\

Do not copy only the deploy directory. The container build also needs the production source beneath src.

Option B: Extract a supplied ZIP file

Extract the ZIP and move or rename the extracted repository folder so that this file exists:

D:\ai\mcp\WebAccess.MCP\deploy\compose.yml

Avoid an accidental double folder such as:

D:\ai\mcp\WebAccess.MCP\WebAccess.MCP\deploy\compose.yml

Option C: Clone with Git

If the person distributing WebAccess.MCP provides a Git repository URL, install Git and clone it:

winget install --exact --id Git.Git

Close and reopen PowerShell after Git installation, then run:

$AiRoot = "D:\ai"
Set-Location (Join-Path $AiRoot "mcp")
git clone <repository-url> WebAccess.MCP

Replace <repository-url> with the trusted URL supplied by the project owner.

Verify the repository

$AiRoot = "D:\ai"
$WebAccessRoot = Join-Path $AiRoot "mcp\WebAccess.MCP"

Test-Path (Join-Path $WebAccessRoot "deploy\compose.yml")
Test-Path (Join-Path $WebAccessRoot "Containerfile")
Test-Path (Join-Path $WebAccessRoot "src\WebAccess.MCP\WebAccess.MCP.csproj")

All three commands must return True.

6. Create Installation Secrets

WebAccess.MCP needs a local PostgreSQL password and SearXNG secret. Generate unique values rather than copying secrets from another computer.

Open PowerShell and run:

$AiRoot = "D:\ai"
$DeployRoot = Join-Path $AiRoot "mcp\WebAccess.MCP\deploy"
Set-Location $DeployRoot

function New-HexSecret {
    $bytes = New-Object byte[] 32
    $generator = [System.Security.Cryptography.RandomNumberGenerator]::Create()
    try {
        $generator.GetBytes($bytes)
    }
    finally {
        $generator.Dispose()
    }

    -join ($bytes | ForEach-Object { $_.ToString("x2") })
}

@"
WEBACCESS_POSTGRES_PASSWORD=$(New-HexSecret)
SEARXNG_SECRET=$(New-HexSecret)
"@ | Set-Content -Encoding Ascii .env

Verify that the file exists without printing its secret values:

Test-Path .env

The repository ignores deploy\.env. Keep it private, do not send it to anyone, and do not commit it to Git.

7. Build and Start WebAccess.MCP

From D:\ai\mcp\WebAccess.MCP\deploy, run:

.\Start-WebAccessStack.ps1

The script creates deploy\.env with random installation secrets if needed, verifies Podman and Compose, and runs the entire Compose stack. The first run downloads the base images and builds WebAccess.MCP. It can take several minutes because the Playwright image includes Chromium and its Linux dependencies.

Check the services:

podman compose --project-name webaccess-mcp ps

Expected result:

  • postgres is running and healthy.
  • searxng is running and healthy.
  • webaccess is running.

Compose waits for PostgreSQL and SearXNG to become healthy before starting WebAccess.MCP.

In Podman Desktop, open Containers. The three services should appear in a webaccess-mcp (compose) group. Expand the group to inspect status, ports, and logs.

If a service does not start:

podman compose --project-name webaccess-mcp logs --tail 200

8. Verify the Running Services

Verify both local ports:

Test-NetConnection 127.0.0.1 -Port 28080
Test-NetConnection 127.0.0.1 -Port 28081

Both results should include:

TcpTestSucceeded : True

Verify the dedicated SearXNG instance:

(Invoke-RestMethod "http://127.0.0.1:28080/config").instance_name

The expected name is:

WebAccess.MCP SearXNG

The /mcp URL is a protocol endpoint, not a normal website. Opening it in a browser is not a complete MCP test. LM Studio will perform the MCP handshake in a later step.

9. Download a Tool-Capable Model in LM Studio

WebAccess.MCP supplies tools, but the selected language model decides when and how to call them. Choose an instruct/chat model with tool-use or function-call support. A plain base model is not suitable.

In LM Studio:

  1. Open Discover (Ctrl+2).

  2. Search for a tool-capable instruct model appropriate for the computer.

  3. Select a GGUF quantization. A 4-bit option is a practical starting point for many computers; larger quantizations need more RAM or VRAM.

  4. Download the model.

  5. Confirm in My Models that it was stored beneath:

    D:\ai\llm\models
    
  6. Open Chat and load the model.

Prefer a model with enough context for tool schemas and returned web content. At least 16K context is a useful starting point when the model and hardware support it. Model availability changes frequently, so this guide does not lock the installation to one model family.

If LM Studio cannot use MCP tools reliably with the chosen model, first confirm that the model card advertises tool/function calling. Then try a stronger instruct model or a less aggressive quantization if the hardware permits.

10. Introduce WebAccess.MCP to LM Studio

LM Studio 0.3.17 and later supports remote MCP servers by URL.

  1. Keep the Podman stack running.
  2. In LM Studio, open the Program tab in the right sidebar.
  3. Select Install > Edit mcp.json.
  4. If the file is empty, enter:
{
  "mcpServers": {
    "webaccess": {
      "url": "http://127.0.0.1:28081/mcp"
    }
  }
}

If the file already contains MCP servers, add only this property inside its existing mcpServers object:

"webaccess": {
  "url": "http://127.0.0.1:28081/mcp"
}

Preserve the existing entries and include commas between JSON properties.

This is a remote Streamable HTTP MCP server:

  • Do not add command or args.
  • Do not add authentication headers.
  • Do not use http://127.0.0.1:28080; that is SearXNG, not MCP.
  • Do not use localhost if local security software resolves it unexpectedly; use the exact 127.0.0.1 URL shown above.
  1. Save mcp.json.
  2. Confirm that webaccess appears and is enabled in the Program tab.
  3. Start or return to a chat with the tool-capable model loaded.
  4. Enable the WebAccess.MCP tools for that chat if LM Studio asks.

11. Test LM Studio and WebAccess.MCP Together

Ask the model:

Use web_search to find the official LM Studio MCP documentation. Return the page title and source URL.

LM Studio should display a web_search tool call and its result.

Then test the browser tools:

Open the official LM Studio MCP documentation URL, report the page title, and list the first five links.

WebAccess.MCP has 15 tools. LM Studio should show those tools as available when the MCP connection is healthy.

The browser context is intentionally long-lived. Navigation and interaction state persist across tool calls even though the MCP HTTP transport is stateless.

12. Start and Stop the System

Start a normal session

  1. Start Podman Desktop.
  2. Make sure the Podman machine is running.
  3. Open PowerShell and run:
Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp up --detach
  1. Start LM Studio.
  2. Load the desired tool-capable model.
  3. Confirm that webaccess is enabled in the Program tab.

Stop a normal session

Close LM Studio if desired, then run:

Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp stop

This preserves the containers and PostgreSQL page cache.

Start the stopped containers again

Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp start

Remove containers but preserve data

Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp down

This removes the containers and private network but preserves the PostgreSQL volume.

13. Update WebAccess.MCP

Before updating, stop the stack:

Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp down

Replace the supplied repository files with the newer version, or use Git:

Set-Location "D:\ai\mcp\WebAccess.MCP"
git pull

Do not overwrite or delete deploy\.env.

Rebuild and start:

Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp up --detach --build

The LM Studio mcp.json entry does not need to change as long as the endpoint remains http://127.0.0.1:28081/mcp.

14. Optional Full Integration Test

This section is for maintainers or advanced troubleshooting. Install the .NET 10 SDK, keep the stack running, and execute from the repository root:

Set-Location "D:\ai\mcp\WebAccess.MCP"
dotnet run --project ".\src\WebAccess.MCP.TestRig\WebAccess.MCP.TestRig.csproj" -- `
    --mcp-url "http://127.0.0.1:28081/mcp" `
    --real-searxng `
    --real-searxng-engine google `
    --real-searxng-engine brave `
    --real-searxng-engine duckduckgo

The TestRig validates the HTTP MCP transport, the 15-tool contract, browser state and interactions, page caching, and the externally managed SearXNG service. External providers can still rate-limit or challenge automated search requests.

15. Troubleshooting

Podman commands are not recognized

Close and reopen PowerShell after installing Podman Desktop. If the commands remain unavailable, return to Podman Desktop onboarding or Settings > Resources and install Podman and Compose.

Podman cannot connect

Open Podman Desktop and start the Podman machine. Then retry:

podman info

If the machine cannot start, verify WSL 2:

wsl --status

LM Studio cannot connect to WebAccess.MCP

  1. Confirm LM Studio is version 0.3.17 or later.

  2. Confirm the URL is exactly http://127.0.0.1:28081/mcp.

  3. Confirm webaccess is enabled in LM Studio's Program tab.

  4. Run:

    Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
    podman compose --project-name webaccess-mcp ps
    Test-NetConnection 127.0.0.1 -Port 28081
    podman compose --project-name webaccess-mcp logs --tail 200 webaccess
    
  5. Check that mcp.json is valid JSON.

A host port is already in use

Identify the owning process:

Get-NetTCPConnection -State Listen -LocalPort 28080,28081 |
    Select-Object -Property LocalAddress, LocalPort, OwningProcess

Stop or reconfigure the conflicting application. Do not substitute port 18080; that port belongs to an unrelated deployment.

PostgreSQL rejects the password after .env was changed

PostgreSQL initializes its password only when its data volume is first created. Restore the original WEBACCESS_POSTGRES_PASSWORD.

If the password is lost and deleting the WebAccess.MCP page cache is acceptable, perform an intentional reset:

Set-Location "D:\ai\mcp\WebAccess.MCP\deploy"
podman compose --project-name webaccess-mcp down --volumes
podman compose --project-name webaccess-mcp up --detach --build

down --volumes permanently deletes this stack's PostgreSQL data. Do not use it for normal shutdown.

Search fails while browser tools work

  1. Open http://127.0.0.1:28080/config.
  2. Inspect the searxng and webaccess logs in Podman Desktop.
  3. Confirm the dedicated SearXNG service is healthy.

External search engines can temporarily fail, rate-limit requests, or present anti-bot challenges. WebAccess.MCP does not bypass those restrictions.

The Compose group is missing in Podman Desktop

Confirm Podman Desktop is connected to the same Podman machine used by PowerShell. Starting with the exact --project-name webaccess-mcp command adds the Compose labels Podman Desktop uses to display the services as one group.

LM Studio saves models somewhere else

Return to My Models, change the model directory to D:\ai\llm\models, and use LM Studio's own directory controls to move or redownload models. Do not manually reorganize a model while LM Studio is running.