Install, update and check a runner on your own machine, including the virtual display on Linux.

A runner is the machine that hosts the browser, device or HTTP client a run uses. On self-serve plans, every run uses Autonomy's runners and there's nothing to install.

On Enterprise, runs can also execute on your own machines: inside your network, next to a private environment. This page is for the people who look after those machines.

What you need

Host	Web and API	Android	iOS (coming soon)
Linux (x86_64 or arm64)	Yes	With the Android SDK and an emulator or device	No
macOS (Intel or Apple silicon)	Yes	With the Android tools	With Xcode and an iOS simulator

Outbound HTTPS only. The runner connects to Autonomy; nothing connects to it.
On Linux, an Android emulator needs an x86_64 host with KVM (/dev/kvm). A host with 4 vCPUs and 8 GB of RAM runs one emulator.
Xcode and iOS simulators aren't installed for you. They're for iOS testing, which is coming soon.

Autonomy registers your runner for your organization and sends you three things: the install URL, an install token and a runner token (rn_…). The runner token is shown once. Store it like a password.

Install

Run this as the user the runner will run as:

export AUTONOMY_INSTALL_TOKEN="<install token>"
curl -fsSL "<install URL>/install.sh" \
  | bash -s -- --yes --base-url "<install URL>"

The installer sets up the runtime, the browser and device tools, and the autonomy-labs command in ~/.local/bin. On Linux it also installs Xvfb, the virtual display the browser needs (see below).

Then put the runner token and the settings Autonomy sent you in ~/.autonomy/labs/.env, and make the file private:

chmod 600 ~/.autonomy/labs/.env
autonomy-labs doctor

Keep it running

On Linux, run it as a service:

autonomy-labs service install
autonomy-labs service start
autonomy-labs service status
autonomy-labs logs

On macOS, run autonomy-labs --poll from a LaunchAgent as the same user that owns ~/.autonomy/labs.

Check a runner

autonomy-labs doctor checks everything a run needs and exits with 0 when the runner is ready. Add --json for a machine-readable report. On Linux without a display, it checks virtual display (Xvfb) and then that a headed browser opens a page.

autonomy-labs --version shows the installed build.

Virtual display on Linux

Runs use a headed Chrome, because many sites block headless browsers as bots. On a Linux server with no screen, the runner starts its own virtual display with Xvfb when DISPLAY isn't set. If the host already has a display, the runner uses it.

The installer installs Xvfb with your package manager (apt-get, dnf, pacman or zypper). If it can't, it prints the command to run as root. Until Xvfb is installed, the runner refuses web runs instead of taking them and failing:

sudo apt-get install -y xvfb
autonomy-labs service restart

Update

autonomy-labs update

The update waits for the run in progress, and its cleanup, to finish before it swaps the runner. It never cuts a run short. Afterwards it reinstalls the browser and device tools and runs doctor again. To update only the tools, run autonomy-labs --update-tools.

When a runner stops

Exit code	Meaning
`0`	Stopped on purpose, for example for an update.
`75`	A temporary problem. The service restarts it.
`78`	It can't run work until someone fixes the host: a bad token or settings, no display or browser, or an unfinished update. The service doesn't restart it in a loop. Run `autonomy-labs doctor` to see what's wrong.

A run that a runner picks up but can't begin because of a problem on the runner ends as Couldn't start, isn't billed, and says "This run couldn't start because the runner had a problem. Run it again."

Owners and admins can turn on Infrastructure alert in Organization → Notifications to hear about runner and device capacity problems.

Runners