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

Set up and operate remote machines with RunMacro Manager

Activate the same workspace license on target machines and open RunMacro; Manager Agent connects automatically and each machine becomes Online. Closing RunMacro only makes it Offline; activation and seat occupancy persist. Signing in to RunMacro Manager only displays Machine IDs already bound to that license. To move a license, use Release license / Remove key on the machine holding the seat.

Prerequisites

An active trial or license with RunMacro Manager entitlement. Workspace policy supplies the actual machine, Job, Runner, schedule, and result-retention limits.
RunMacro installed and activated with the same workspace license on every target Windows machine.
Manager Agent connects automatically while RunMacro is open; there is no manual Connect/Disconnect step. Enable Start Manager Agent with Windows only if RunMacro should be ready immediately after Windows sign-in.
A GitHub Gist containing Packages published in RunMacro’s catalog format — the same Gist that RunMacro Studio publishes to (Cloud Sync / Export RunMacro package) and RunMacro Runner reads for Check updates — plus a token with suitable read/write access. Never place credentials in Package notes or documentation.
HTTPS access to manager.runmacro.app, the Manager API, GitHub API, and the Gist from both browser and targets.
An app-key Package that needs no interactive opening password. Browser Jobs also need a valid per-machine HTTPS Google Sheets URL and a compatible Chrome/CDP environment.

Supported modes

Desktop Mode — A Desktop Job runs in the target Windows session and uses its real pointer, keyboard, windows, and display. Manager does not create an interactive desktop or make a locked desktop usable.
Browser Mode — A Browser Job uses Chrome/CDP. Manager requires a valid Google Sheets URL per target, accepts window geometry and concurrent sessions, and applies those values transiently without replacing the local Runner cache.
RunMacro Runner — Manager Agent downloads the Package pinned by revision and SHA-256, then asks RunMacro Runner to open it unattended. Runner remains the execution runtime and accepts only one local or Manager reservation at a time.

What it does

RunMacro Manager is the web control plane for a workspace of connected Windows machines. A Manager Agent inside RunMacro on each machine reports status, receives commands, downloads the exact pinned Package from the same GitHub Gist that Studio publishes to and Runner reads, and hands it to RunMacro Runner. Manager can inventory machines and Packages, create Desktop or Browser Jobs across one or more targets, schedule time-based work or link Jobs into a pipeline, monitor progress, pause/resume/stop active runs, and review bounded logs and results. Manager coordinates execution; each workflow still runs on the target machine with that machine’s environment and permissions.

When to use it

Control and monitor one Package across multiple Windows machines from a central browser.
Dispatch an immediate Job to ready machines or create a durable schedule that can wait for targets to become available.
Run Browser batches with a per-machine Google Sheets profile source and bounded concurrent sessions.
Build pipelines with Run after a source Job or Schedule, optionally enable Only run if source succeeds, inspect lineage, and review operational logs and results centrally.

When not to use it

You only need a same-PC Package schedule with Every N minutes, Countdown, or Windows startup; use the local Scheduler.
The target cannot keep RunMacro/Manager Agent available or provide the interactive Windows session required by Desktop automation.
The Package needs an opening password or a password-type input at run time; Manager has no unattended prompt channel for those secrets.
Complete large outputs or unbounded logs are mandatory; Manager result transport and retention are intentionally limited.

Configuration steps

On every target, install RunMacro and activate the workspace license. Activation persistently binds its Machine ID to the license and occupies one seat.
Open RunMacro. Manager Agent connects automatically and the bound machine becomes Online. When RunMacro closes or loses network access, the same machine remains listed and becomes Offline.
Optionally enable Start Manager Agent with Windows when RunMacro should be ready after Windows sign-in. This controls application startup only; it is not an activation or connection switch.
Open https://manager.runmacro.app, choose a language, and enter the workspace license key. Use Remember this device only in a trusted browser; the web app does not retain the license key.
Open Settings › GitHub Gist Storage. On first setup enter Gist ID and token, select Test Connection, then Save Configuration. Later, blank unchanged fields keep their stored values.
If a conflict appears, choose the intended source of truth: the RunMacro-reported configuration or Manager’s encrypted configuration. Compare the masked Gist IDs and do not alternate sources without knowing which is current.
Open RunMacro Packages, choose Refresh Catalog, verify Package name, channel, version, revision, and SHA-256, then select Create Job.
Name the Job, fill non-sensitive inputs, and choose targets. For Desktop, prepare an interactive session; for Browser, provide a Google Sheets URL for each machine plus window size and concurrent sessions.
Choose Run now, Run by time (Once/Daily/Weekly with an IANA timezone), or Run after and pick a source Job or Schedule (optionally enable Only run if source succeeds) for a pipeline, then create the Job or schedule.
Open Job detail to inspect each machine, loop/command/percent progress, log, and results. Pause, Resume, or Stop when policy allows. Canceling a schedule removes future or pending occurrences but never stops a Job that already started.

Every option explained

Activation, Online presence, and Windows startup

Activation binds the Machine ID and keeps the seat until that machine releases the key. Agent connects automatically while RunMacro is open; closing it only changes presence to Offline and never releases the seat. Windows startup controls launching RunMacro, not Manager connection.

The license key selects a workspace and is sent for authentication only. A regular session lasts 24 hours; Remember this device uses a revocable 30-day secure session instead of browser license-key storage. Sign out or Switch license changes the visible workspace scope.

Gist ID, token, Test, Save, and conflict

Manager points at the same GitHub Gist that Studio publishes to and Runner reads, so sharing one Gist ID keeps the same Package catalog everywhere. Initial setup needs both Gist ID and token; once configured, blank fields retain stored values. Save uses a configuration version to detect concurrent changes; a conflict requires selecting RunMacro or Manager as the source of truth. The token is stored encrypted server-side and is never exposed to the browser.

Machines and Packages

Machines filters Online/Offline/Idle/Running/Paused targets, supports rename and notes when policy allows, and shows Agent/protocol versions. Packages supports search, sort, notes, catalog refresh, and exact revision plus SHA-256 inspection.

Desktop Job

Sends scalar inputs and Desktop runtime to each selected target. Run now accepts only online, idle, compatible machines. File and folder inputs are paths on the target, not on the computer displaying Manager.

Browser Job

Requires a per-machine HTTPS Google Sheets URL, window size of at least 320×240, and 1–99 concurrent sessions in the current protocol. Workspace policy and real machine resources can impose lower bounds.

Run now and unavailable machines

An immediate Job rejects offline, busy, paused, revoked, or protocol-incompatible machines. The dialog can remove unavailable targets before retrying, and the Package is pinned when the Job is created.

Time schedule

Manager supports Once, Daily, or Weekly (with specific weekdays) recurrence in an IANA timezone. Offline, busy, or paused targets may be selected and waited for at trigger time, but an occurrence can still misfire, overlap, or time out waiting for resources.

Run after (Job or Schedule) and pipelines

The Run after mode accepts two source kinds: a nonterminal Job (Job badge) or an active Schedule (Schedule badge). With a Job source, the child triggers once when that Job reaches an executed terminal state. With a Schedule source, the child re-triggers each time a Job produced by the source schedule finishes, which is useful for recurring pipelines. Enable Only run if source succeeds to trigger only when the source is SUCCESS; when it is off (default) the branch runs regardless of outcome. Lineage records parent, root, and depth; cycles are rejected when linking and a source Schedule cannot be deleted while dependents exist.

Monitoring and controls

Jobs refresh about every 15 seconds, Job detail about every 5 seconds, and workspace/machine state about every 20 seconds. Policy can allow pausing running runs, resuming paused runs, and stopping active runs individually or in a batch.

Logs, tables, and result files

Manager displays a log tail, message/error, duration, metadata, a table with a truncation flag, and up to three small JSON/TXT/PNG/JPEG files. A storage warning means some result data was omitted by limits. Terminal results are kept for 7 days by default unless workspace policy sets a different retention.

Workspace capabilities and limits

The session supplies permissions for machine management, Gist, Job creation/scheduling/control, and results. Policy also supplies machine, active Job, concurrent Runner, target, schedule, and result-retention limits; current displayed values are authoritative.

Expected result

Enrolled machines appear with Online/Offline presence and current activity, while the catalog exposes pinned Packages. A Job creates one run per machine, updates progress, and accepts supported controls. At completion, Manager shows status, a risk-reduced log tail, a bounded result table, and accepted small files. Schedules remain in the workspace, materialize Jobs by time or pipeline dependency, and preserve lineage for investigation.

Real example

Run a Desktop Package on two idle machines

Activate the same workspace license on both targets and open RunMacro so Manager Agent connects automatically; enable startup only if needed, then confirm both show Online · Idle on Machines.
Export the Desktop workflow as an app-key Package with no opening password, publish it to Gist, and refresh the Manager catalog.
From the Package choose Create Job, name it, provide non-sensitive inputs, and select both machines if workspace limits allow.
Choose Run now. Open Job detail, confirm each target moves from Fetching to Running, and watch per-machine command/percent progress.
At completion inspect message, log tail, bounded table/files, and storage warnings; retrieve needed artifacts before retention expires.

Schedule a Browser Job and link a post-processing Job

Publish app-key Browser and post-processing Packages, then verify runtime, channel, revision, and SHA-256 in the catalog.
Create a Daily Browser schedule in the intended timezone, select targets, and enter a valid Google Sheets URL per machine with a small test concurrency.
Create a second schedule with Run after and pick a source: either the running source Job, or the source Schedule itself so the post-processing repeats after each scheduled run; enable Only run if source succeeds to run only on success.
Use Schedules to inspect next/source/pending Job, then open Job detail to verify Pipeline root, Parent Job, and Depth.
Review each machine result. If the source becomes canceled/skipped, verify the dependent branch is skipped; if targets wait too long, inspect the resource terminal reason.

Limitations and failure cases

Manager Agent runs inside RunMacro and is not a Windows service. The target must be powered on, signed into Windows, and running RunMacro/Agent; verify startup after enabling it.
Offline never releases activation or a seat. If Team A–E occupy 5/5, turning C off remains 5/5; only releasing the key on C produces 4/5, after which F can activate and return to 5/5.
Desktop Jobs need an interactive, unlocked desktop with stable resolution/DPI and no competing pointer/keyboard use. Manager does not remove Desktop-environment constraints.
Run now rejects offline, busy, paused, or incompatible targets. Schedules may wait for these states, but an occurrence can still end through misfire, overlap, or resource timeout.
Each machine has one runtime reservation shared by local runs, the local Scheduler, and Manager. An active run makes other sources wait or fail according to their launch type.
A password-locked Package needs the password at Create Job: the form shows a Package password field. The remote Runner never opens a password dialog. A wrong or missing password fails the Job with password_required.
Password-type and sensitive-marked inputs are omitted from the Manager catalog. Do not repurpose a text input to transport secrets; Job values cross the Manager API on their way to targets.
Browser Jobs currently accept only per-machine HTTPS Google Sheets profile URLs on docs.google.com. A local file on the browser computer is not uploaded as a substitute.
An execution snapshot is capped at 64 KiB, 100 scalar inputs, and 8,192 characters per string in the Agent protocol. Per-machine Browser configuration can reach the cap before Job creation.
Manager scheduling supports Once, Daily, Weekly, Run after Job, and Run after Schedule. The local Scheduler separately supports Every N minutes, Countdown, startup, and local settings; the two systems can contend for the same Runner.
Cancel schedule removes future or pending occurrences only; a started Job continues until Stop is sent. Once and After Job schedules complete after one occurrence.
Pipelines have current hard caps of 20 levels and 20 direct dependents. A Run after source must be a nonterminal Job or an active Schedule; a canceled/skipped source does not execute its dependent branch, and with Only run if source succeeds enabled the branch is skipped when the source fails, stops, or is canceled.
Capabilities and limits come from workspace policy. The UI may disable Job creation, schedules, controls, or results; never assume values from another workspace or an older plan.
Telemetry is bounded rather than a full output stream: logs are at most 40 lines/6 KiB; tables at most 20 columns, 100 rows, and about 20 KiB; up to 3 files, 16 KiB each and 24 KiB total, within an 80 KiB terminal payload.
Results use short-term workspace retention and may be truncated or omitted with storage warnings. Manager does not replace complete report files on the target machine.
Logs and results use marker-based redaction to reduce exposure, not to guarantee removal of all PII or secrets. Keep credentials out of inputs, logs, profile names, notes, and remotely viewed outputs.
Catalog refresh pins a Package by Gist revision and SHA-256. Editing the file after a Job is created does not mutate that Job’s artifact; refresh and create a new Job/schedule for the new release.
The web UI polls as a baseline — roughly 20 seconds for workspace state, 15 seconds for lists, and 5 seconds for Job detail, pausing while the tab is hidden — and a realtime WebSocket channel invalidates snapshots for faster updates. Data can still be briefly stale if that channel is interrupted.

Tips & common mistakes

Machine not Online: open RunMacro on that target and inspect Manager status, license validity, HTTPS access, and App/Agent/Protocol versions. No manual Connect step is required or exposed.

A password_required start failure means the Package is locked and the Job did not supply the correct password. Enter the package password when creating the Job, or export an app-key release, refresh the catalog, and create a new Job.

For a Gist conflict, compare masked Gist IDs and confirm ownership before choosing. RunMacro source publishes the machine-reported configuration; Manager source returns the encrypted stored configuration to Agent without exposing its token to the browser.

For Browser, start with one machine, 1–2 sessions, and harmless Google Sheets test data. Increase targets or sessions only after revision, profile source, viewport, and bounded results are correct.

Manager is an orchestration channel, not a secret vault or full report archive. Keep credentials in dedicated storage and full outputs on targets; send only the minimum summary/result needed for monitoring.

Verification details

core/qmacro_manager_agent.py
core/qmacro_manager_qt.py
ui/qmacro_runner_window.py
server/qmacro_manager_coordinator.js
website/src/components/manager/CreateJobModal.tsx
website/src/pages/manager/ManagerJobDetailPage.tsx
tests/test_qmacro_manager_runner_bridge.py