@aloud/runner

Runs Aloud usability studies in a real browser on your own machine.

That is the whole point of it. The browsers run here, so a study can open localhost, a staging site behind your VPN, or anything else Aloud's servers could never reach. The connection is outbound only: nothing listens on a port, and the server holds no address for this machine.

npm install -g @aloud/runner

aloud login          # approve this machine in your browser
aloud start          # waits for studies and runs them here

The first aloud start downloads Chromium, about 350 MB, once.

Commands

| Command | What it does | | --- | --- | | aloud setup | Inspect this machine and complete whatever setup remains | | aloud login [--token <token>] | Connect this machine to your workspace | | aloud start [--once] [--quiet] [--no-update] | Update, then wait for studies and run them here | | aloud status | What is set up, what is not, and whether it is running | | aloud allow <host> | Approve a private or local host on this machine | | aloud mcp | Connect an MCP host to the web workspace selected by its MCP access token | | aloud logout | Forget the token on this machine | | aloud --version | Print the installed runner version |

Updates

Starting with 0.3.1, aloud start asks the connected Aloud server which official runner release it recommends. If a newer one is available, it installs that exact @aloud/runner version and relaunches it before claiming work. It never replaces code during an active study.

Starting with 0.3.3, a runner that is already waiting does the same update automatically while it is idle. A customer does not have to notice a release, stop the process, or start it again.

If an optional update cannot be installed, the terminal says why and a still-compatible runner may continue. If the server requires the update, nothing starts and the command exits non-zero with the manual repair command. --no-update is available for managed environments, but it cannot make an incompatible runner claim work.

Production test email

Live production email forms need an address the target is expected to accept. Set it once under Machines → Production test email in Aloud. The workspace setting survives runner restarts and upgrades and is sent only to the authenticated machine that claims a study. Use {sessionId} in a Gmail plus address or QA catch-all to give every participant a distinct address; {runId} is also available when one address per run is intentional. Recorded actions and evidence contain only [synthetic email], never the rendered address.

UTA_SYNTHETIC_EMAIL_TEMPLATE remains available as a fallback for standalone and managed CLI environments.

MCP access

Open the web app's Settings → MCP access, create a connection, and paste the configuration it shows into your MCP host. That configuration starts aloud mcp with a separate delegated token. The stdio process keeps no research database of its own: studies, runs, evidence, and reports are stored in the web workspace and remain available there after the MCP host disconnects.

Runner tokens (utar_…) and MCP tokens (utam_…) are intentionally different. A runner can claim browser work but cannot create studies as a user; an MCP token is tied to the member who created it, their current workspace role, and a narrow list of capabilities. Either token can be revoked from the web app without deleting existing study history.

What it will open

Public websites work automatically. The runner grants only the public domain named by the current lease, checks DNS again immediately before launch and on every later network request, and forces private-network access off for that study. The grant disappears with the lease and is never written to ~/.aloud/credentials.json.

Localhost, private IPs, and names that resolve inside a private network remain explicit. Add those once with aloud allow <host>; that list lives only on this machine. Nothing the server sends can widen it, and cloud metadata and link-local targets are always refused.

The token is stored in that same file at mode 0600, and aloud logout deletes it. Revoking a machine from the web app takes effect immediately, including for a study already running.

Requires Node 20 or newer. Source: https://github.com/dfala/user-testing-ai