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

How to run packaged workflows in QMacro Runner

QMacro Runner executes .qmacro packages without editing the Studio workflow. Open a package, complete its inputs, choose Desktop or Browser, and run it. Enabled reporting writes JSON for Desktop, while multi-profile Browser runs also have a result CSV. Preserve JSON when several same-day runs matter, and remember that password inputs are not cached.

Prerequisites

The .qmacro file must exist, be fully downloaded, and come from a source you can assess; password packages require the author-provided password.
Every displayed input needs a value, and a TXT Lines source must exist with at least one data line.
Browser mode requires CSV or Google Sheet rows with the provider-specific ID column, a working provider, and any requested API, token, or executable.
Reports, Telegram, Cloud/Gist, and Scheduler require their Runner settings plus write access to the selected output directories.

Supported modes

QMacro Runner — This is the dedicated QMacro surface. Desktop Mode performs real screen control, while Browser Mode drives Chrome/CDP profiles. Mode, thread, and browser locks express author intent in the UI rather than providing an absolute enforcement guarantee.

What it does

QMacro Runner opens a .qmacro package, builds its metadata-defined input form, applies bound values to the decrypted workflow, and executes in Desktop or Browser mode. App-key packages open silently; password packages request the password before commands are loaded. For a foreign package containing detected high-risk commands, Safe Mode starts enabled and skips those commands unless an operator deliberately disables it and confirms. The window supports loops, speed control, pause and stop, parallel Browser profiles, CSV or Google Sheet profile sources, live step status, logs, and diagnosis. With report creation enabled, Desktop completion writes JSON only; multi-profile Browser execution writes JSON and updates a result CSV. JSON filenames are based on QMacro name and date, so a later same-day run can overwrite the prior report, and Browser detail retention is capped at the latest 1,000 outcomes. Scheduler, Cloud/Gist, reusable configs, and Telegram cover recurring operations.

When to use it

Use it after receiving a packaged QMacro when the operator only needs to supply business inputs and execute allowed settings.
Use it for Browser batches driven by CSV or Google Sheet profiles with parallel windows and per-profile outcomes.
Use it for one-time, daily, weekly, interval, countdown, startup, or dependent schedule automation.
Use it when Gist updates, reusable run configs, diagnostics, local reports, or Telegram notifications are part of operations.

When not to use it

Do not use Runner to edit commands, selectors, or workflow structure; return to the source PMacro in Studio.
Do not disable Safe Mode for an unfamiliar package until every listed dangerous command is understood.
Do not use exported run config as a secret store because its JSON may contain current inputs, paths, and profile rows.
Do not choose Browser without a valid profile source and the required provider or API environment; use Desktop for direct screen control.

Configuration steps

Launch QMacro Runner and choose Open QMacro, or press Ctrl+O, to select a package. An idle window can be retargeted to another QMacro.
Enter the QMacro password when prompted. App-key packages open without a prompt; then confirm the displayed workflow name, version, and description.
If a dangerous-command card appears, review its list and leave Safe Mode enabled for a package not authored on this machine.
Complete every field under Input variables, using the supplied text, password, number, folder, file, TXT, checkbox, or select control.
Set Mode, Repeat, and Speed. Author locks are intended UI state, but cached, imported, or scheduled settings can reapply mode, threads, or browser values, and some other controls remain editable. A repeat value of zero displays as infinite.
For Browser mode, open Background run settings, choose window count and provider, set CDP/viewport/arrangement options, and import CSV or Google Sheet profiles.
Decide whether to Remember information for the next run. Password-type inputs are skipped, but exported configs still require a privacy review.
Select Run. Use Pause/Resume and the Stop state of the run button while watching current command, elapsed time, step count, and status.
Open View log when needed. Desktop completion writes JSON but no CSV on the current path. After a Browser batch, inspect Results by profile, JSON, and the result CSV; details retain only the latest 1,000 outcomes.
Once the run is reliable, use Schedule manager, upload/download, Check updates, Telegram, or import/export config. Copy the JSON first when another same-day run must not replace it.

Every option explained

Open QMacro and password

Open QMacro and Ctrl+O select another file. App-key packages open silently; only password packages show QMacro Protected with a password field, OK, and Cancel.

Runner header actions

Visible controls are light/dark theme, VI/EN language, Open QMacro, Schedule manager, and Settings. Workflow name, version, and description appear beside the logo.

Settings and tools menu

The complete menu includes Runner settings, AI / API, Import config, Export config, Switch mode, Error diagnosis, Upload / Sync QMacro, Download QMacro..., Check updates, and User guide.

Mode, repeat, and speed

Mode offers Desktop and Browser. Repeat accepts 0–999999, where zero is ∞. Speed accepts 1–10. The package can disable mode, thread, or browser controls as UI intent, but cache/config/schedule restoration can reapply those values and some related controls remain editable.

Package input form

Runner renders eight types: text, password, number, folder, file, txt_lines, checkbox, and select. Folder/File/TXT add pickers, password masks characters, number uses a numeric control, and select uses packaged choices. System variables in defaults resolve relative to the QMacro context.

TXT Lines per loop

The TXT file is read as UTF-8 with BOM support and blank lines removed. Sequential cycles through lines; Random chooses a line for each loop. An empty source prevents the run from starting.

Remember information

Remember information for the next run caches non-password inputs under a hash of the absolute QMacro path, not the package ID. Separate qmacro_config_cache stores mode, threads, provider, ports/viewport, window options, and individual provider/local-profile fields such as local name/folder/port, profile ID, API URL/path; it does not store profile rows or the CSV/Sheet profile source. The cache currently also writes provider_token as a string in settings.json, even though the per-provider token is additionally stored through DPAPI.

Safe Mode

A foreign QMacro with detected dangerous commands shows a warning card, summary, and Enable Safe Mode: skip dangerous commands while running, checked by default. Disabling it triggers another confirmation before normal execution.

Run, pause, stop, and status

Run becomes Stop while active, and Pause resumes the same run. Schedule opens schedule creation. Status shows Ready, Running, Paused, Finished, or Error plus current step, elapsed time, and step count.

Logs, diagnosis, and profile results

View log expands details. AI Error Diagnosis offers Medium - Free and Smart (AI). After a multi-profile run, Results by profile shows #, Profile, Browser, Loop, Status, Attempt, Reason, and Open report.

Browser windows and providers

Chrome windows accepts 1–99. Browser/Profile lists Default Chrome, GPM Login, AdsPower, Hidemium, Dolphin Anty, GoLogin, and Octo Browser. Anti-detect providers may require a license key, local app, paid plan, or separate SDK.

Chrome and viewport configuration

Default Chrome exposes Starting CDP port and Delete newly created profiles after run. Shared options are viewport width × height from 100–9999, automatic window positioning, full-page Browser failure screenshot, and arrangement scale Auto/100/125/150/175/200/250/300%.

Profile sources and provider fields

Profile sources offer Import CSV, Add from Google Sheet, and View sample file. Runner conditionally shows API URL, API token, executable/path, and provider notes, hiding irrelevant fields. CSV rows need the provider-specific profile ID column.

Runner settings

The Runner tab contains Default mode, Download/save path, Report folder, Auto-close after success, Show log on error, Check for updates before run, Gist ID, GitHub Token, and Default channel, with Choose, Save, and Cancel controls.

Notifications, Telegram, and report files

The Notifications / Telegram tab exposes Enable notifications, Bot Token, Chat ID, Machine name, report creation, Desktop failure screenshot, JSON/CSV attachment choices, completion and interruption notices, insecure TLS allowance, and Send test. Current Desktop completion creates JSON only; CSV comes from the Browser result path, so a requested CSV attachment may not exist.

Import and export run config

The JSON contains QMacro identity and current mode, loops, speed, inputs, threads, provider, port, viewport, arrangement, provider URL/path, and profile source/rows. Provider token is omitted from the exported payload. Runner asks before importing a mismatched ID or channel.

Cloud/Gist and updates

Upload / Sync sends the current file. Download QMacro... asks for name/cloud filename, destination, and whether to open afterward. Check updates compares ID/channel/version and the public hash computed from root metadata and workflow commands. It does not compare the encrypted payload content_sha256, so child-macro-only or image-only changes can be missed when public version/hash values stay unchanged. Cloud validation accepts a legacy macro.json package or a protected manifest/payload pair; replacement creates a .bak-... before atomic write.

Schedule and Schedule manager

Schedules expose Enabled, run at PC startup, Time or After another schedule triggers, Success/Always/Failure conditions, and delay. Time types are Once, Daily, Weekly, Every N minutes, and Countdown, with date/time/weekdays, mode, loops, speed, and Browser/profile settings. Manager actions are Add, Edit, Run now, Delete, Enable/Disable, Stop, Details, View/Export result, and Refresh.

Expected result

Runner loads the workflow, applies bound inputs, and moves from Ready through Running to Finished, Finished with errors, Stopped, or Error. Author locks guide the UI but do not prevent every cached, imported, or scheduled override. With reporting enabled, Desktop writes Results_*.json but no CSV; multi-profile Browser execution also updates a CSV and shows OK, failed, and skipped totals. A same-QMacro JSON can be overwritten later that day, and Browser details retain at most the latest 1,000 outcomes.

Real example

Run a password-protected Browser QMacro across several profiles

Open the QMacro, enter the author-provided password, and verify its displayed name, version, and channel.
Supply the URL and TXT input, and keep Safe Mode enabled if the unfamiliar package shows a dangerous-command warning.
Choose Browser mode, open Background run settings, select the provider, and import a CSV with the required profile ID column.
Use a small window count, set viewport and full-page failure capture, then run one controlled batch.
Open Results by profile and review the JSON plus Browser result CSV before increasing concurrency or scheduling the job.

Schedule a daily Browser run with Telegram reporting

Complete one successful manual Browser run, choose the report folder, and enable report creation in Runner settings.
On the Telegram tab, enter Bot Token, Chat ID, and machine name; enable completion and report attachment, then use Send test.
Create a Daily schedule with the tested time, mode, loops, threads, and profile configuration.
Save the schedule, enable Scheduler, and keep RunMacro open before the scheduled time.
After execution, use Schedule manager to inspect status and profile outcomes; preserve the JSON if another run that day must not overwrite it.

Limitations and failure cases

Runner does not edit workflow structure. Field names, bindings, commands, and selectors must be changed in the source PMacro and re-exported.
Author mode/thread/browser locks are UI intent rather than a security boundary. Path-based cache, imported configs, or schedules can apply values to locked fields, and some related controls remain editable.
A password package cannot open with a missing or wrong password; an app-key package can be opened by compatible RunMacro and is not access-secret protection.
Current QMacro packages carry no author signature. Encrypted integrity checks do not replace verification of the file source.
Safe Mode skips only commands recognized by the current dangerous-command scanner; it does not prove that the entire workflow is harmless.
After an operator disables Safe Mode and confirms, a foreign package can execute high-risk actions with the permissions of the current RunMacro session.
Every displayed input is validated as required. A required checkbox must be checked, and an empty TXT source stops the run before execution.
Cache identity is the absolute QMacro path, not package ID: moving a file loses its old cache, while replacing a package at the same path inherits that cache. qmacro_config_cache does not store profile rows/source, but it stores individual mode/provider/local-profile fields and can currently persist provider_token in settings.json. Export config is ordinary JSON and may contain inputs, paths, URLs, profile rows, and profile source data.
The exported config omits the provider token, but it cannot identify secrets placed in custom input fields; sanitize and inspect it before sharing.
Report text is redacted for known sensitive patterns, yet local paths, QMacro identity, outputs, profile labels, failure reasons, and operational metadata may remain.
Files are created only when reporting is enabled and the destination is writable. Desktop completion writes JSON but no CSV; multi-profile Browser runs also have CSV. JSON uses QMacro name plus date, so a later same-day run can overwrite it, and Browser detail retention is limited to the latest 1,000 outcomes.
Browser execution needs provider-specific profile IDs. API URLs, tokens, executables, anti-detect applications, SDKs, plans, and licenses vary by provider.
Timed schedules run only while RunMacro is open and Scheduler is enabled. Only one startup schedule can be active, and the Store build cannot pass a macro file through StartupTask.
Updates and sync require Gist credentials, matching identity/channel data, and network access. Update comparison uses the public root metadata/commands version and hash, not the encrypted payload content hash, so child-only or image-only changes can be missed. A failed pre-run check can continue with the local file.
Pause and stop are cooperative with engine and command checkpoints; a blocking operating-system or provider operation may not react immediately.
Browser full-page failure capture uses current content dimensions without scrolling or changing viewport and can fall back to the current viewport image.

Tips & common mistakes

Keep Safe Mode enabled for an unfamiliar QMacro. Disable it only after verifying the source and understanding every high-risk command listed.

An app-key package opens without a prompt, but that does not make it trusted. Encryption protects stored contents; provenance depends on distribution.

Before Export config, clear sensitive inputs and inspect profile rows: exported JSON is unencrypted even though provider token is omitted. Protect settings.json too because qmacro_config_cache can currently retain that token locally.

Enable reporting and run a small batch before scheduling or increasing windows. Desktop has JSON only; Browser also has CSV and profile details, but copy JSON when multiple same-day runs must be retained.

Timed schedules require the application to remain open. With Check updates, verify version and actual behavior: network failure or child/image-only changes can leave Runner using the local package.

Verification details

ui/qmacro_runner_window.py
ui/qmacro_scheduler_dialog.py
core/qmacro_scheduler.py
core/qmacro_sync.py
core/run_report.py
tests/test_qmacro_scheduler.py