Pulse Worker — Setup Guide (run this before using Pulse)

Pulse is bring-your-own-compute: the part that drives a real mobile device (the Pulse worker) runs on your own machine, not on qualien's servers. The qualien.ai dashboard talks to it over http://localhost:8787. So before you can run a Pulse test, you install a small toolchain once and start the worker.

This guide targets macOS (Intel or Apple Silicon); Windows and Linux sections are at the end. Budget ~20–30 minutes the first time; after that, starting the worker is one command.

Open the Pulse dashboard in a Chromium browser (Chrome or Edge) — Safari blocks an https:// page from calling http://localhost.

1. Install the prerequisites

You need: Homebrew, Python 3.10+ (3.12 recommended — the AI agent needs 3.10+), a JDK, Node.js, the Android SDK + a system image + an emulator, and Appium with the uiautomator2 driver.

Homebrew (skip if you have it) — https://brew.sh:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Python, JDK, Node:

brew install python@3.12 openjdk node

Appium + the Android driver:

npm install -g appium
appium driver install uiautomator2

Android SDK + an emulator — the simplest is Android Studio (GUI):

Install it: brew install --cask android-studio (or from developer.android.com).
Open it → More Actions → SDK Manager, and install: SDK Platform (API 34), Android SDK Platform-Tools, Android Emulator, and a system image matching your CPU — x86_64 on Intel, arm64 on Apple Silicon.
More Actions → Virtual Device Manager → Create device (e.g. Pixel 6, API 34).

Add this to your shell profile (~/.zshrc) so tools find the SDK:

export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"

Prefer no GUI? If you have the qualien repo (contributors), cd worker && ./setup.sh installs and verifies all of the above automatically, including the emulator and the Python venv. See "Contributor shortcut" below.

2. Install the worker

Recommended — pip (isolated, via pipx):

brew install pipx && pipx ensurepath
# with AI agent mode (recommended); use a 3.10+ interpreter:
pipx install --python python3.12 "qualien-pulse-worker[agent]"

This puts a pulse-worker command on your PATH. (Deterministic-only, no AI: pipx install --python python3.12 qualien-pulse-worker.)

Contributor shortcut (from the repo):

git clone https://github.com/qualienai/qualien.git
cd qualien/worker
./setup.sh          # installs JDK, Android SDK + emulator, Node, Appium, and a 3.10+ venv with [agent]

3. Configure keys

You don't need your own Anthropic key unless you use the local agent mode. Deterministic runs and every other AI feature — self-heal, element resolution, recovery, visual checks — run through qualien.ai (our model access), authenticated by your worker token. So a worker token is all most people need.

Variable	Needed for	Where it comes from
`PULSE_WORKER_SECRET`	AI self-heal / element resolution / recovery / visual checks (all via qualien.ai)	Generate a worker token in the Pulse dashboard and paste it here — you don't invent this value.
`ANTHROPIC_API_KEY`	Local agent mode only — the worker's agent calls Claude directly	Your own Anthropic key. Leave it unset if you don't use agent mode.

Optional: PULSE_CONTROL_PLANE_URL (default https://qualien.ai), PULSE_APPIUM_HOST / PULSE_APPIUM_PORT, ANDROID_HOME, JAVA_HOME.

4. Start the worker

With pip/pipx — start your emulator (from Android Studio's Device Manager, or emulator -avd <name>) and Appium (appium), then:

ANTHROPIC_API_KEY='sk-ant-…' PULSE_WORKER_SECRET='your-secret' pulse-worker serve

From the repo — one command boots the emulator + Appium for you:

cd qualien/worker
ANTHROPIC_API_KEY='sk-ant-…' PULSE_WORKER_SECRET='your-secret' ./run.sh

The worker serves on http://127.0.0.1:8787. Leave the terminal open (Ctrl-C stops it).

5. Verify

curl http://127.0.0.1:8787/health     # → {"status":"ok", …}
pulse-worker env                       # lists what's ready / missing

Then open qualien.ai → Pulse in Chrome/Edge. The status should read Worker online. If you installed agent mode, flip Agent: on and try "explore the app and write a smoke test for guest checkout, then run it."

Using a physical Android phone (instead of the emulator)

Enable Developer options → USB debugging, plug in, accept the prompt.
adb devices should list it as device.
Start the worker (skip emulator autostart if using run.sh): PULSE_NO_AUTOSTART=1 ./run.sh — or just pulse-worker serve with pip.

A physical phone is often faster and sidesteps emulator ABI issues (below).

Troubleshooting (the common ones)

Symptom	Fix
Dashboard says worker offline	Is the worker running on `:8787`? Are you using Chrome/Edge, not Safari?
Agent mode errors / SDK import fails	Your Python is 3.9. Reinstall with a 3.10+ interpreter: `pipx install --python python3.12 "qualien-pulse-worker[agent]"` (repo: re-run `./setup.sh`). Check `python3.12 --version`.
`address already in use … 8787`	An old worker is still running: `lsof -ti tcp:8787 \| xargs kill`
Requests to `localhost` blocked	You're on Safari — switch to Chrome/Edge (Safari blocks https→http localhost).
Emulator won't boot / app crashes on launch	Intel needs an x86_64 image; Apple Silicon needs arm64. arm64-only APKs crash on Intel emulators — use a physical arm64 phone or an x86_64/universal build.
macOS "claude" cannot be opened (agent mode)	Clear quarantine on the bundled runtime once — for a pipx install: `xattr -rd com.apple.quarantine "$(pipx environment --value PIPX_LOCAL_VENVS)/qualien-pulse-worker"` (repo: the path under `worker/.venv/.../claude_agent_sdk/_bundled/claude`).
A prerequisite is missing	`pulse-worker env` reports what's not ready. Repo users can re-run `./setup.sh` (idempotent).

Windows

The worker itself runs on Windows — Python, Appium, and the Android SDK/emulator are all cross-platform. There's no bootstrap script (setup.sh is macOS), so you install the prerequisites manually, then use the pip path from step 2.

Prerequisites (PowerShell, using winget):

winget install Python.Python.3.12
winget install Microsoft.OpenJDK.21
winget install OpenJS.NodeJS.LTS
winget install Google.AndroidStudio
npm install -g appium
appium driver install uiautomator2

Then, as in step 1, use Android Studio → SDK Manager / Device Manager to install the SDK Platform (API 34), Platform-Tools, Emulator, an x86_64 system image, and create a virtual device. Set the SDK path (System Properties → Environment Variables, or per-session):

$env:ANDROID_HOME = "$env:LOCALAPPDATA\Android\Sdk"
$env:Path += ";$env:ANDROID_HOME\platform-tools;$env:ANDROID_HOME\emulator"

Install + run the worker (pipx on Windows: python -m pip install --user pipx; python -m pipx ensurepath):

pipx install --python python3.12 "qualien-pulse-worker[agent]"
# start your emulator + Appium, then:
$env:PULSE_WORKER_SECRET = "your-token"; pulse-worker serve

Agent mode on Windows is not yet verified — the worker's AI agent spawns a bundled runtime whose Windows support we haven't confirmed. Deterministic runs and the control-plane AI features (self-heal, resolution, recovery, visual) work on Windows with just a worker token; if you need agent mode specifically and hit a runtime error, use macOS/Linux for now. A physical Android phone over USB (with the vendor's ADB driver) works well on Windows — adb devices should list it.

Linux

Install the JDK, Android SDK (+ platform-tools, emulator, a system image), Node, and Appium (appium driver install uiautomator2) via your package manager, then pipx install --python python3.12 "qualien-pulse-worker[agent]" and pulse-worker serve (managing the emulator/Appium yourself).