ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use Agent-Browser with Microsoft Edge

Configure agent-browser to launch Microsoft Edge, verify the executable, automate pages, and troubleshoot platform-specific issues.

By the ScreenshotNeo team1 October 20268 min read

Short answer: agent-browser documents a custom browser executable through --executable-path and AGENT_BROWSER_EXECUTABLE_PATH. Its default installation downloads Chrome for Testing, so using Microsoft Edge requires you to locate the Edge binary on your operating system, point agent-browser at it, and verify that the exact Edge channel and agent-browser version work in your environment.

The official material reviewed documents the custom executable mechanism but does not provide a complete, Edge-specific recipe or compatibility matrix. Treat the commands below as a configuration path to validate locally rather than as a guarantee for every Edge release, platform, or channel.

1. Install agent-browser

The documented global installation is:

npm install -g agent-browser
agent-browser install

agent-browser install downloads Chrome for Testing by default. That browser is separate from Microsoft Edge and is the fallback to use when you do not provide a custom executable.

Other documented installation routes include:

  • npx agent-browser for one-off use.
  • A project-local npm installation.
  • Homebrew.
  • Cargo.
  • Building from source.

On Linux, install the required system dependencies when needed:

agent-browser install --with-deps

2. Find the Microsoft Edge executable

You must provide the path to the Edge executable installed on your machine. The exact path changes with the operating system and Edge channel.

Platform Typical Edge Stable path How to verify
Windows C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe Check the Edge shortcut target or inspect the installation directory.
macOS /Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge Right-click the app, choose “Show Package Contents,” then inspect Contents/MacOS.
Linux /usr/bin/microsoft-edge Run command -v microsoft-edge or command -v microsoft-edge-stable.

Microsoft publishes channel-specific executable locations for its Edge DevTools MCP server. Those locations are useful when locating Edge, but that documentation describes a different tool and does not independently verify agent-browser compatibility.

Check the path before configuring agent-browser

# macOS or Linux
ls -l "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
command -v microsoft-edge
command -v microsoft-edge-stable

# Windows PowerShell
Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"

If the command or file check fails, find the actual installation path first. Do not assume that making Edge the operating system’s default browser changes the executable used by agent-browser.

3. Launch agent-browser with Edge

Use the documented CLI option:

# macOS
agent-browser --executable-path "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" open https://example.com

# Linux
agent-browser --executable-path /usr/bin/microsoft-edge open https://example.com

# Windows PowerShell
agent-browser --executable-path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" open https://example.com

For repeatable scripts, set the documented environment variable instead:

# macOS or Linux
export AGENT_BROWSER_EXECUTABLE_PATH="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
agent-browser open https://example.com

# Windows PowerShell
$env:AGENT_BROWSER_EXECUTABLE_PATH = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
agent-browser open https://example.com

The CLI flag is the most explicit option for a single command. The environment variable is convenient for CI jobs, shell profiles, and project scripts.

4. Make the setting persistent

agent-browser configuration supports an executable path setting named executablePath. The documented precedence is:

  1. User configuration.
  2. Project configuration.
  3. Environment variables.
  4. CLI flags.

Higher-priority values override lower-priority values. Keep the Edge path in project configuration only when every developer and CI runner uses a compatible path. Otherwise, prefer an environment variable supplied by each machine.

When debugging, print or inspect each possible source of configuration and temporarily use the CLI flag. A successful CLI launch confirms the path without ambiguity from a stale project file or environment variable.

5. Use the standard agent-browser workflow

Once Edge launches, the interaction model is the same documented workflow used with the default browser: open a page, take an accessibility snapshot, act on element references, and take another snapshot after the page changes.

# Open a page in Edge
agent-browser --executable-path "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge" open https://example.com

# Inspect the accessibility tree
agent-browser snapshot

# Use a reference returned by the snapshot
agent-browser click @e1

# Inspect the updated page
agent-browser snapshot

References such as @e1 come from the snapshot output. Always refresh the snapshot after navigation, clicks, dialog changes, or dynamically rendered content because the page structure and references can change.

Typical scripted sequence

#!/usr/bin/env bash
set -euo pipefail

EDGE="/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
agent-browser --executable-path "$EDGE" open https://example.com
agent-browser snapshot
# Replace @e1 with the reference returned for the target control.
agent-browser click @e1
agent-browser snapshot

6. Connect to an existing browser

agent-browser also documents connecting to an existing browser through the Chrome DevTools Protocol using Chrome-oriented examples. The reviewed documentation does not establish an Edge-specific CDP procedure. If you use this mode with Edge, verify that the Edge process was started with the required remote-debugging configuration and confirm the connection in your target environment.

Launching an owned browser with --executable-path is easier to reason about because agent-browser controls the process it starts. An existing-browser connection can be useful when another tool owns the session, but it adds port, profile, process-lifecycle, and version variables.

7. Edge channels and profiles

Stable, Beta, Dev, and other Edge channels normally have different executable locations. Select one channel deliberately and record it in your development or CI configuration. Do not silently switch channels between local development and deployment.

  • Use a dedicated automation profile when the page requires a clean session.
  • Do not rely on cookies or extensions from your personal profile unless the workflow explicitly needs them.
  • Run the same Edge channel in CI that you validated locally.
  • Pin or record the agent-browser version so a later upgrade does not change launch behavior without review.

8. Troubleshooting

“Executable not found” or a similar launch error

Cause: the path is wrong, quoted incorrectly, or points to a directory instead of the executable.

Fix: verify it with ls -l, command -v, or PowerShell Test-Path. Use an absolute path and quote paths containing spaces.

agent-browser still launches Chrome

Cause: the custom path was not passed, the environment variable is misspelled, or a higher-priority CLI/configuration value overrides it.

Fix: run one command with the explicit --executable-path flag, then inspect project and user configuration and the value of AGENT_BROWSER_EXECUTABLE_PATH.

Edge opens and closes immediately

Cause: the executable may be incompatible with the installed agent-browser version, the profile may be locked, or the browser process may fail before a page is created.

Fix: try a clean profile, close existing Edge processes, confirm the Edge channel, and reproduce with a minimal open https://example.com command. Record the exact Edge and agent-browser versions.

Linux reports missing shared libraries or sandbox dependencies

Cause: the host does not have the browser dependencies required by the automation stack.

Fix: run agent-browser install --with-deps where supported, then install any remaining packages required by your Linux distribution and container image.

Snapshots are empty or controls are missing

Cause: the page has not finished rendering, content is inside a frame, or the accessibility tree changed after navigation.

Fix: wait for the page state used by your workflow, take a fresh snapshot, and inspect the resulting references. Treat references from an earlier snapshot as stale after page changes.

Permission, policy, or corporate-management errors

Cause: managed Edge installations can impose policies that affect profiles, downloads, extensions, or remote debugging.

Fix: test with the same managed installation used in deployment, ask the administrator which policies apply, and use a permitted dedicated profile where possible.

9. Reliability and performance considerations

  • Startup cost: launching a new Edge process for every URL is slower than keeping a controlled session alive. Reuse a session only when its state and isolation requirements are understood.
  • Determinism: use a fixed Edge channel, consistent viewport and profile settings, and refreshed snapshots after every state-changing action.
  • Parallelism: multiple browser processes consume substantial CPU and memory. Start with a small worker count and increase it while monitoring the host.
  • Isolation: separate profiles prevent cookies, local storage, and extensions from one job affecting another.
  • Retries: retry transient navigation failures with a bounded backoff, but capture diagnostics before retrying so persistent configuration errors are visible.
  • CI parity: validate the executable path, Edge channel, OS image, and agent-browser version in the same environment that runs production automation.

10. Choosing between Edge and the bundled browser

Choice Best when Trade-off
Chrome for Testing from agent-browser install You want the documented default with fewer host-specific variables. It does not reproduce an Edge installation or Edge-managed policies.
Microsoft Edge via --executable-path You must test the Edge channel used by your users or organization. You must locate and validate the binary for every target environment.
Existing-browser/CDP connection Another process must own the browser session. Ports, profiles, process lifetime, and Edge-specific compatibility require additional verification.

11. Or skip the browser setup

If your goal is simply to capture a clean screenshot or PDF, ScreenshotNeo provides a website screenshot API and MCP server without requiring you to install or manage a local Edge browser. It accepts one GET request and can return PNG, JPEG, WebP, or PDF.

See the ScreenshotNeo API documentation for all options. A basic request is:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp
import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response identifies the page verdict and billing status with X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and try the API with 1,000 screenshots each month at no charge.

12. FAQ

Does setting Edge as my default browser make agent-browser use Edge?

No. The operating system’s default-browser association controls which app opens links. agent-browser uses its configured executable or its documented default browser.

Is every Edge channel supported?

The reviewed documentation does not publish an Edge-specific compatibility matrix. Validate the exact channel, OS, and agent-browser version you plan to run.

Should I use the environment variable or the CLI flag?

Use the CLI flag for a one-off diagnostic or command. Use AGENT_BROWSER_EXECUTABLE_PATH for shell scripts, CI, and machine-specific configuration.

Can I keep using agent-browser commands after switching to Edge?

The documented open, snapshot, interaction, and refreshed-snapshot workflow remains the same after the browser starts. Edge-specific launch and CDP behavior still needs local verification.

What should I record for a reproducible bug report?

Record the operating system, Edge channel and version, agent-browser version, executable path, configuration source, command, and the complete error output.

Keep reading