Docs

RunMacro Documentation

Learn RunMacro from basics to advanced.

Everything you need to start and master RunMacro — from basic commands to advanced automation workflows.

Ctrl K

🧩 Features

Open a Chrome profile for Browser Mode

Switch to Browser Mode, click open-Chrome-for-authoring, choose Default Chrome, set a Profile name, leave Port and Viewport as they are, then click Open Chrome. Re-enter the same profile name later to reopen that same profile.

Prerequisites

A paid license. Browser Mode is gated twice: entering the mode and pressing run.
Google Chrome installed (for the Default Chrome path). RunMacro looks in PATH, the registry, then the Program Files folders.
A free TCP port in the 9000–9999 range.
Windows — window resizing and auto-tiling are Windows-only.
For multi-profile browsers: that app must be running with its local API reachable; Dolphin Anty and GoLogin additionally need a token.
The Smart HTML extension is not required for basic Browser Mode — only for the element picker, Explorer and Smart Record.

Supported modes

Browser Mode

What it does

Browser Mode drives Chrome through the DevTools Protocol (CDP) instead of taking over your real mouse and keyboard. Before running a macro you pick a browser source: Default Chrome — RunMacro launches Chrome itself in an app-managed profile folder with a remote debugging port; or a multi-profile browser (GPM Login, AdsPower, Hidemium, Dolphin Anty, GoLogin, Octo Browser) — RunMacro asks its local API to open a profile and hand back the debug port.

When to use it

Automating a website while still using the computer for other work.
Running several different logged-in profiles at the same time.
Keeping login sessions between runs (reuse the same profile name).
You already use a multi-profile browser and want RunMacro to drive its profiles.

When not to use it

Automating desktop software or games — use Desktop Mode.
You are on the Free tier: Browser Mode is a paid feature.

Configuration steps

Choose Browser Mode on the mode screen (or press 2).
Click the open-Chrome-for-authoring button. The browser source chooser appears.
Pick Default Chrome and click Open.
In the Open authoring profile dialog: type a Profile name (default Runmacro). The Folder line below shows the real profile path.
Leave the pre-filled Port as it is, or click Random for another free port.
Set the Viewport if needed (default 800x800). The real window is about 90px taller because it includes the Chrome UI bar.
Click Open Chrome. RunMacro launches the browser and waits for the CDP port to answer.
Once open, the port is written into the main window port field. Author your macro against that Chrome window.
When you press run, pick the browser source again then Import CSV with the profile list for multi-threaded runs.

Every option explained

Profile name

A free-text box that also lists existing profiles. A new name creates a new profile; re-entering an old name reopens it with its login session. Special characters become _ in the folder name, so two different names can map to the same folder.

Folder

Read-only. Shows the real profile path and updates as you change the name. Profiles live in the app data folder, not in your personal Chrome profile.

Port

The remote debugging port, 9000 to 9999, pre-filled with a free one. The Random button picks another free port. In multi-threaded runs each window gets its own port automatically.

Viewport (width x height)

The page content size, 800x800 by default. The real window is about 90px taller for the Chrome UI bar. Keep the viewport identical between authoring and running so recorded coordinates stay valid.

Open profile folder

Creates the folder if missing then opens it in File Explorer. Useful for inspecting or backing up profile data.

Delete profile data

Deletes all profile data, including cookies and login sessions. It refuses while Chrome is using the folder, and always asks for confirmation first (defaulting to No).

Browser source

Pick Default Chrome or a multi-profile browser. Each source needs different settings: see the list below.

GPM Login

Needs an API URL (default http://localhost:9495) and the path to GPMLogin.exe. The first CSV column is profile_id.

AdsPower

Default API URL http://local.adspower.net:50325, no token needed. First CSV column is user_id. Its API allows one call per second, so RunMacro throttles automatically.

Hidemium

Default API URL http://127.0.0.1:2222 (Hidemium 4); older versions use port 5555. First CSV column is uuid.

Dolphin Anty

Default API URL http://localhost:3001 and an API token is required to avoid 401 errors. First CSV column is profile_id.

GoLogin

Uses the gologin Python SDK, so that package must be installed; no API URL is entered. Requires a dev token, which only exists on GoLogin paid plans. First CSV column is profile_id.

Octo Browser

Default API URL http://localhost:58888, no token needed since you are signed in inside the Octo app. First CSV column is uuid. Requires the Base plan or higher.

Parallel threads / Size / Auto-arrange windows / Window layout scale

Available in the run configuration dialog. Threads sets how many windows open at once. With auto-arrange off, RunMacro only resizes and leaves the position the browser chose. Use Window layout scale when Windows Display Scale mis-tiles the windows.

Expected result

A Chrome window opens with its own profile inside a RunMacro-managed folder (not your real Chrome profile), with a remote debugging port open. Macros run in that window without taking over your mouse or keyboard.

Real example

Example: open a Default Chrome profile to author a macro

Enter Browser Mode and click the open-Chrome-for-authoring button.
Pick Default Chrome and click Open.
Type shop_A as the Profile name, keep the pre-filled Port, Viewport 800x800.
Click Open Chrome and wait for the window.
Sign in to the site inside that window — the session is kept in the shop_A profile.
Author your macro. Next time, entering shop_A returns you to that signed-in session.

Example: run one macro across 5 profiles in parallel

Write and test the macro on a single profile first.
Press run. Pick the browser source (Default Chrome or your multi-profile browser).
In the configuration dialog, set Parallel threads to 5.
Click View sample file to see the format, then Import CSV with your profile list. The first column must match the chosen source.
The remaining CSV columns become variables you can use inside the macro.
Click OK. RunMacro opens up to 5 windows at once, each with its own port and profile.

Limitations and failure cases

Browser Mode needs a paid license; the Free tier is blocked at mode entry.
Window resizing and auto-tiling are Windows-only.
Special characters in a profile name become _, so My Profile and My/Profile share one folder.
Profiles whose names start with codex_, test_ or _ are hidden from the suggestion list, though typing the name still opens them.
If no port in 9000–9999 is free, no further window can open.
API URLs for non-GPM sources are currently not remembered between app sessions — you must re-enter them.
On run, a macro containing commands Browser Mode does not support is blocked, with those commands listed.
Chrome profiles hold cookies and login sessions: only run macros you trust on a profile signed into an important account.

Tips & common mistakes

Use meaningful profile names (shop_A, mail_02) and write them down — re-entering the exact name is the only way back into that session.

Delete profile data also wipes cookies and login sessions, with no way back. Make sure you picked the right profile.

Keep the Viewport the same between authoring and running. Changing it shifts elements, and steps that rely on coordinates may click the wrong place.

Window opens but the macro will not run: check that the port in the main window field matches the port the open Chrome is using.

Multi-threaded runs consume RAM and CPU per window. Try 2–3 threads first and increase gradually rather than jumping to 20.

Verification details

core/chrome_cdp_session.py
core/browser_providers.py
core/background_chrome_runner.py