Install and setup

One command per platform. The agent brings its own Node, Python and browser, so nothing has to be installed first.

Platforms: Linux amd64 · macOS arm64 · Windows amd64/arm64
Disk: About 400 MB, all under ~/.qaclan/
Port: 7823 free, for the local app

Install

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/install.sh | sh

Windows (PowerShell)

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
irm https://raw.githubusercontent.com/qaclan/agent/master/install.ps1 | iex

That is the whole installation. It puts qaclan on your PATH and provisions an isolated runtime — Node, a Python virtual environment and Chromium — under ~/.qaclan/runtime/. Nothing is installed globally. Allow a few minutes for the browser download, then open a new terminal window so the command is recognised.

Check it worked

qaclan version

qaclan status

The first prints one line, such as qaclan 0.1.12. The second reports that you are signed out, with no active project — the expected state on a fresh install. Carry on to Getting started from there.

A command not found error means PATH has not been picked up yet. Open a fresh terminal, or source your shell rc file, and try again.

Upgrade

Re-run the installer above. It replaces the binary in place and leaves your database, scripts and runtime alone. The releases page is where you check whether there is anything newer.

Uninstall

qaclan uninstall --yes

This deletes your local data

It removes ~/.qaclan/ entirely — the database, every recorded script, run history, environments and credentials. To rebuild only the browser runtime, use qaclan reset-runtime instead. If your work is synced, you can restore it on a new machine with qaclan pull.

What the Windows command does

The first line lets the installer script run for the current PowerShell session only — Windows blocks unsigned remote scripts by default, and -Scope Process limits the change to that window. It reverts when the window closes.

The second puts the binary at ~/.qaclan/bin/qaclan.exe and adds that folder to your user PATH. Restart the terminal afterwards.

If you downloaded the binary by hand

The installer scripts provision the runtime for you. A binary taken straight from the releases page has had nothing done for it, so run the bootstrap once yourself:

qaclan setup

It is idempotent — re-running skips completed steps. Its seven flags, along with reset-runtime and set-upload-cap, are in the CLI reference.

What lands on disk

Everything lives under ~/.qaclan/ — on Windows, %USERPROFILE%\.qaclan\.

Path	Contents
`qaclan.db`	SQLite: projects, features, suites, runs, collections, environments
`scripts/`	Your recorded and imported test scripts, as readable files
`uploads/`	Files captured during a recording, so a replay can upload them again
`screenshots/`	Screenshots written when a script fails
`config.json`	Your auth key, active project and server URL
`bin/`	The `qaclan` binary, when setup placed it there
`runtime/`	The isolated runtime: `node_modules/`, a Python `venv/`, and `browsers/` holding Chromium
`runtime/runs/`	Per-run artifacts, one directory each: the rendered scripts, the shared `state.json`, console logs and network logs

Run artifacts sit inside runtime/, so rebuilding it clears them too. Everything else is outside and survives — which is what makes qaclan reset-runtime safe. Rebuilding a broken runtime is covered in the FAQ.

Uninstalling when the binary itself is broken

These remove the binary and the data directory without going through qaclan. They do not clean shell history or rc files.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/qaclan/agent/master/uninstall.sh | sh

Windows

irm https://raw.githubusercontent.com/qaclan/agent/master/uninstall.ps1 | iex