Docs

RunMacro Documentation

Create your first robot, then go further as needed.

Clear step-by-step guides to create, run, and improve robots for repetitive computer work.

Ctrl K

📦 Features

How to create and export an encrypted RunMacro package

RunMacro package export converts a tested workflow into an encrypted package for RunMacro Runner with optional inputs and Desktop or Browser defaults. Choose a destination from which existing relative references resolve, then test with the old source unavailable: export performs no dependency preflight and does not guarantee that every missing item was embedded.

Prerequisites

The workflow must contain at least one command and should be tested in the Desktop or Browser workspace that will be distributed.
Save an editable .pmacro source first as the maintained recovery copy, but saving it does not make its directory the dependency base for current RunMacro package export.
Choose a .qmacro destination from which relative paths resolve, and keep referenced images and child macros reachable. A password-protected child RunMacro package cannot be repackaged automatically.
Upload / Sync additionally requires a configured Gist ID, GitHub token, and network access.

Supported modes

Desktop Mode — Export from the Desktop workspace when the runner should default to real mouse and keyboard control. The active Studio workspace is authoritative for the stamped mode.
Browser Mode — Export from the Browser workspace to stamp Browser/CDP as the default, then define provider, profile, viewport, and thread behavior for the runner.

What it does

Export turns the workflow currently open in Studio into a .qmacro file intended for RunMacro Runner. Supported command values can be bound to runner inputs, so the value entered at run time replaces the exact marked command field rather than creating an unrelated variable. The export dialog defines package identity, Desktop or Browser defaults, thread and browser behavior, and a manual input form. Every RunMacro package produced by current RunMacro is encrypted with AES-256-GCM: an empty password uses the application key, while a password derives a separate key. The exporter attempts to embed discovered images, selector data, and submacros, but it does not pass the saved PMacro as the dependency base: relative references resolve from the destination .qmacro directory, and unresolved items can remain external without warning because this export path has no dependency preflight.

When to use it

Use it to hand off a workflow that operators should launch from RunMacro Runner instead of editing command rows in Studio.
Use it when each run needs operator-supplied accounts, URLs, quantities, folders, files, or line-oriented TXT data.
Use it when the exporter should attempt to collect image assets, selector data, and nested submacros; destination placement and clean testing are still required because unresolved references may remain external.
Use it to stamp a workflow name, version, description, and controlled runner defaults before sharing or cloud sync.

When not to use it

Do not treat RunMacro package as the only editable source; keep the original .pmacro when the workflow will continue to evolve.
Do not use the no-password mode when access must be limited to people who possess a separate secret.
Do not treat the package as publisher authentication. Current exports are encrypted and integrity-checked but unsigned.
Do not treat export success as proof of self-containment; a child macro or image that cannot be resolved may remain an external reference without a warning.

Configuration steps

Open or build the workflow in Studio, switch to the intended Desktop or Browser workspace, and complete a representative test run.
Save an editable .pmacro copy with Editable PMacro project (*.pmacro). If the workflow is unsaved or dirty, choose Save .pmacro first, Export RunMacro package anyway, or Cancel; saving does not change the export dependency base.
For a run form, right-click a supported command row, choose Mark as RunMacro package input, and set its display label, type, default, and TXT behavior when applicable.
Choose Export as RunMacro package..., then select the .qmacro filename and a destination from which existing relative dependencies resolve. That filename seeds the package name for this export.
On Information, review Workflow name, Version, and Workflow description.
On Protection, leave both fields empty for app-key encryption, or enter and confirm a password of at least six characters to gate opening.
On Run configuration, set defaults and operator edit permissions for mode, threads, browser/profile, CDP, viewport, and the visible local-profile preset.
On Inputs, keep or remove marked bindings, add manual rows where needed, configure types and select choices, and use Preview form.
Select Save RunMacro package configuration; this path performs no dependency preflight. Upload/sync or defer as appropriate, but open the finished file in RunMacro Runner with the old source unavailable to expose external references.

Every option explained

Unsaved .pmacro decision

Save .pmacro first preserves an editable source with Editable PMacro project (*.pmacro), Export RunMacro package anyway continues without saving it, and Cancel stops export.

Filename and destination

The RunMacro package (*.qmacro) picker selects the destination and filename and appends the extension when omitted. That destination directory, not the source PMacro directory, is the current export base for relative references.

Workflow information

Visible fields are Workflow name, Version, and Workflow description. Defaults normally use the filename, 1.0.0, and a packaged-workflow description.

App-key or password protection

RunMacro package is always encrypted. Empty Password (optional) and Confirm fields select the app key; a supplied password must match its confirmation and contain at least six characters.

Bind a command value as input

The command-row menu provides Mark as RunMacro package input and Unmark RunMacro package input. The mark dialog shows only Display label, Type, Default, and, for TXT Lines, TXT mode. The binding retains the exact row and command field replaced during export.

Commands that can be marked

Supported primary values include Type Text, Paste Text, CDP Navigate, Delay, Show Message, Log Message, Set Variable, Calculate, and AI Text; Smart HTML text-oriented type/select/wait/assert actions; and CDP Popup when its action is type.

Manual input rows

Each visible row contains Use, Variable key, Display label, Type, Default, Options, and an X remove button. The toolbar offers + Add variable and Preview form. Enabled keys must be valid and unique; select requires choices.

Input types

The full row type list is text, password, number, folder, file, txt_lines, checkbox, and select. The binding dialog offers the first six; checkbox and select are created in the manual table.

TXT lines and select choices

TXT Lines supports Sequential or Random selection and a TXT file filter. Select choices use label=value | Option 2; without an equals sign, the label and value are identical.

General run configuration

Visible controls are the Desktop/Browser Default mode, Allow runner to change mode, Windows / threads from 1 to 99, and Allow runner to change threads. The active Studio workspace ultimately determines the exported mode.

Visible Browser export settings

Browser/profile lists Default Chrome, GPM Login, AdsPower, Hidemium, Dolphin Anty, GoLogin, and Octo Browser, plus Allow runner to change browser/profile. Other visible fields are CDP port, viewport width × height, Local profile, Profile port, Profile folder, and Choose.

Completion and Cloud/Gist

Save RunMacro package configuration starts packaging; Cancel creates nothing. After success, choose Upload / Sync now, Open Cloud settings, or Not now. Upload requires a Gist ID and GitHub token.

Expected result

The result is a .qmacro file that current RunMacro always encrypts and RunMacro Runner can open with its stamped identity, form, and configuration. Workflow logic is encrypted; images or child macros are in the payload only when the exporter resolves and embeds them. Password packages prompt, while app-key packages open silently. Legacy unprotected RunMacro packages that contain macro.json remain load-compatible.

Real example

Package a password-protected Browser workflow driven by TXT accounts

Switch Studio to Browser Mode and test navigation and web actions with one sample profile.
Right-click the account-entry command, bind it as TXT Lines, choose Sequential, and point the default at harmless sample data.
Choose Export as RunMacro package..., select Browser settings, use a small thread count, and allow provider changes only when operators need them.
Set a password, save the package, open it in Runner, choose the real TXT source, and import the approved profile list.
Run a small batch and review the Browser profile table, JSON report, and Browser result CSV before handing it to operations.

Ship a nested browser workflow with portable assets

Verify that every child PMacro and Find Image asset works in the source project, then identify their relative references.
Choose a RunMacro package destination from which those references still resolve; saving the parent PMacro does not supply its source directory to export.
Bind the target URL, file, and folder inputs needed by recipients without placing secrets in defaults.
Choose Export as RunMacro package...; the exporter attempts to embed resolved children, images, and selectors but gives no missing-dependency preflight.
Rename or move the old source tree, open the RunMacro package in Runner, and exercise every branch. If one fails, correct placement or paths and export again rather than assuming self-containment.

Limitations and failure cases

RunMacro package is a run package, not a replacement for the maintained PMacro source and its edit history.
No-password export uses an embedded application key. It encrypts the file but any compatible RunMacro installation can open it, so it is not access control.
Passwords must contain at least six characters, have no recovery path in the open flow, and should be delivered separately from the package.
The manifest currently records signed: false. AES-GCM detects payload tampering but does not authenticate a publisher identity.
Public metadata remains readable so Runner can build the identity, input form, and run configuration; workflow logic and embedded assets are the encrypted portion.
A binding can target only the supported primary value of a recognized command. Other fields need workflow variables or source edits.
Runner validates every enabled input as having a value; the current export UI does not expose an optional-input switch.
Select rows require choices, and a TXT Lines source must exist and contain at least one nonblank line when execution begins.
RunMacro package export has no dependency preflight and does not pass the source PMacro as dependency_base_path. Relative references resolve from the RunMacro package destination; unresolved items can silently retain external paths. A password-protected child RunMacro package also cannot be repackaged.
The active Studio workspace overrides stale mode metadata, so authors must switch to the intended workspace before export.
Anti-detect providers still depend on their local application or API, credentials, service plan, and applicable license access.
Cloud upload is a separate optional step; network or credential failure does not remove the successfully exported local package.

Tips & common mistakes

Keep the source PMacro and test the RunMacro package from a clean folder; this quickly exposes any dependency that was not packaged as expected.

Both modes use AES-256-GCM. The important distinction is that RunMacro can open app-key packages, while a password creates a separate access gate.

Never place the password in the description, an input default, or the same delivery location as the RunMacro package; losing it blocks normal Runner access.

Current RunMacro packages are not author-signed. Accept them only from a trusted source and let Runner Safe Mode inspect dangerous commands.

Prefer a command-row binding for a value that must be replaced. A manual input creates a variable but does not rewrite an unrelated command field automatically.

Verification details

ui/main_window.py
ui/qmacro_metadata_dialog.py
ui/qmacro_mark_input_dialog.py
core/qmacro_protection.py
storage/json_store.py
tests/test_qmacro_export_dialog.py