From zero to localhost:7823.

Three steps: get your auth key, install the agent, log in and launch the web UI. The browser opens at localhost:7823 and you're in.

1. Sign up and get your auth key

Create an account at qaclan.com and copy your auth key from Settings → Auth Key.

2. Install the agent

One installer per OS — it puts qaclan on your PATH and provisions the runtime (Node, Python, Chromium). Install locations, flags, and troubleshooting are in Installation.

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

Restart the terminal afterward so qaclan resolves on your PATH.

3. Log in and launch the web UI

Two ways to authenticate on first run — pick one.

Option A — log in from the CLI

$ qaclan login --key <your_auth_key> && qaclan serve

On Windows PowerShell, run the two commands on separate lines.

Option B — paste the key in the web UI

$ qaclan serve

Start without logging in — the first screen prompts for your auth key. Paste it, click Save, you're in.

Either way the browser opens at http://localhost:7823 — start managing your Playwright tests locally.

The building blocks.

A handful of simple ideas — once they click, you know the whole tool. Everything nests like this:

Install.

Download the qaclan binary, then run qaclan setup once to provision the runtime. No system Python or Node.js required — the agent ships the CLI, the web UI, and the runner.

Requirements

• OS Linux (amd64), macOS (arm64), or Windows (amd64 / arm64)
• Disk ~400 MB for the isolated runtime and Chromium browser
• Port 7823 free for the local web UI

Install the binary

The installer places the qaclan binary on your PATH, then provisions the runtime for you. Pick your OS.

Linux / macOS

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

Installs the binary to /usr/local/bin/qaclan. Supports Linux (amd64) and macOS (arm64).

Windows (PowerShell)

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

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 this window. The policy reverts when the window closes. The second line places the binary at ~/.qaclan/bin/qaclan.exe and adds that folder to your user PATH. Restart the terminal afterward so qaclan resolves.

Verify it worked

Confirm the binary is on your PATH and check the installed version with qaclan version:

$ qaclan version
qaclan 0.1.12

qaclan --version prints the same string — use either. A command not found error means PATH is not applied yet — restart the terminal (Windows) or source your shell rc (Linux/macOS), then retry. Compare the version against the releases page to see if an upgrade is available.

Then check agent state:

$ qaclan status
✓ signed out
✓ data dir  ~/.qaclan
✓ no active project

Upgrade

Re-run the installer for your OS — it replaces the existing qaclan binary in place. Your runtime/ folder and local data are left intact.

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

# Windows (PowerShell)
> irm https://raw.githubusercontent.com/qaclan/agent/master/install.ps1 | iex

After an upgrade that bumps the pinned Playwright version, run qaclan reset-runtime followed by qaclan setup --runtime-only to rebuild the runtime cleanly.

$ qaclan reset-runtime          # asks for confirmation
$ qaclan reset-runtime --yes    # skip the prompt
$ qaclan setup --runtime-only   # rebuild afterward

$ git clone https://github.com/qaclan/agent.git && cd agent
$ python3 -m venv env && source env/bin/activate
$ pip install -r requirements.txt
$ playwright install chromium firefox webkit
$ python qaclan.py serve --port 7823

$ qaclan uninstall
? Delete ~/.qaclan (14 projects, 482 scripts)? (y/N)

Authentication.

One auth key per user, tied to your qaclan.com account. Grab it from the dashboard, pass it to qaclan login, you're done.

1. Sign up and get your auth key

Go to qaclan.com and Sign in with Google — Google OAuth is the only sign-in method. An auth key is generated automatically on first sign-up.

Open Settings → Auth Key to view and copy it. The key looks like qc_… (a qc_ prefix followed by a 32-byte url-safe random token).

2. Log in from the agent

$ qaclan login --key <your_auth_key>

Same command on every OS. The agent validates the key against the server, then stores it locally (~/.qaclan/config.json).

From the web UI

If you start qaclan serve without being logged in, the first screen prompts for your auth key. Paste it, click Log in, and you're in.

Regenerate your key

If a key leaks, open Settings → Auth Key → Regenerate Key on qaclan.com. This invalidates the old key immediately — any agent still using it will need to log in again with the new key.

Regenerate Key

Log out

$ qaclan logout

Removes the key from config.json. Subsequent commands (except login, logout, serve) will error until you log in again.

The agent web UI.

Everything you do day-to-day happens here. Start it with qaclan serve, open localhost:7823, and you land on the Scripts page of the active project.

The six sections

Projects.

A project is your workspace — usually one per product. The agent always operates on the active project.

1. Create — project switcher (top-right) → + New project → name it. Created and made active right away.
2. Switch — open the switcher, pick a project. Scripts, features, suites, runs & environments all filter to it.
3. Delete — switcher → Delete project → confirm. Removes its features, scripts, suites and runs.

$ qaclan project delete <project_id>

Features.

Features group scripts by app area. A feature has a channel — web for Playwright browser flows, api for HTTP contract checks.

1. Create — Features → + New feature → name it and pick a channel (web or api).
2. Edit — click a row to rename. The channel is fixed once created.
3. Delete — hover a row → trash → confirm.

Scripts.

A script is a single Python file that drives one logical flow. Record it with Playwright codegen, or write it from scratch in the in-browser editor.

Record a script

1. Scripts → + Record. Set a name, a feature, and a start URL (literal or {{BASE_URL}}).
2. Start recording — a browser opens to that URL; click through your app and every step is captured.
3. Close the browser — the script saves automatically as Playwright code, tagged RECORDED.

Write or smart-edit

Prefer code? + New script opens the in-browser editor with a template. The agent can also review a recorded script and suggest cleaner selectors and stronger assertions.

Template variables

Write {{KEY}} anywhere in a script or its start URL — the active environment fills it in at run time, so one script runs against any environment. Edit any script by clicking it; rename inline; delete from the row menu.

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    context = browser.new_context()   # agent rewrites this at runtime
    page    = context.new_page()

    page.goto("{{BASE_URL}}/login")
    page.get_by_label("Email").fill("{{EMAIL}}")
    page.get_by_role("button", name="Sign in").click()
    browser.close()

Suites.

A suite is an ordered list of scripts you run as a unit. Scripts share browser session state through the suite.

1Create a suite 2Run it

1. Create — Suites → + New suite → name it, pick a channel (web / api).
2. Add scripts — open the suite → + Add scripts → pick from the project. They run in the order you add them.
3. Reorder — drag rows by the handle. Order matters: sign-in before view-dashboard.

Running tests.

Open any suite, hit Run. The run dialog asks for browser, resolution, headless mode, stop-on-fail, and environment.

1Environment 2Browser & resolution 3Run the suite

1Pass / fail totals 2Failure + diagnostics

Run options

Live status & results

The Runs page streams in real time — each row flips QUEUED → RUNNING → PASSED / FAILED, with a total / passed / failed / skipped rollup. A suite passes only if every script passes.

Every run captures status, duration, console & network errors, the failure message, a screenshot on failure, and a step-by-step timeline.

Environments.

Named bags of variables. Apply one at run time and its values are injected into the script subprocess and used to resolve {{KEY}} placeholders. The sidebar item is labelled Environment (singular).

1. Create — Environment → + New environment → name it (dev, staging, prod…).
2. Add variables — + Add variable → set a Key and Value; toggle Secret to mask it in the UI and logs.
3. Use it — pick the environment in the run dialog. Every {{KEY}} resolves; a missing key fails fast before any browser opens.

Cloud sync.

Sync is best-effort. Changes are queued locally and a background worker pushes them to the server. Failures never block the agent — they retry with backoff.

QAClan syncs automatically in the background — keep working offline as long as you like, nothing is lost. The Push (↑) and Pull (↓) buttons in the top bar just force it to happen now.

What syncs

Everything the agent tracks — including your .py file contents:

• Projects, features, suites — and their order
• Scripts — metadata and the file contents
• Environments & variables — values included
• Runs — suite & per-script results, logs, errors

Reports & Analytics. Team plan

See how healthy your tests are across the whole team — at a glance, on qaclan.com.

What it shows

New workspaces show “not enough data” until a suite has run 3+ times — trends need history.

Team collaboration. Pro

Invite teammates, share a common view of the workspace and run history, pay per seat. Any teammate can pull the shared workspace and run the same suites locally.

1. Invite — qaclan.com → Team → Invite → enter an email. They accept by signing in with Google.
2. They get a key — once in, they copy their auth key from Settings → Auth Key.
3. Pull the workspace — qaclan login then qaclan pull (or the Pull button) — every project, script & environment lands locally, ready to run.

$ qaclan login --key <their_auth_key>
$ qaclan pull
✓ 6 projects · 84 features · 482 scripts · 12 environments

Billing: $30 per active seat / month via Paddle — add or remove seats anytime, prorated on the next invoice.

CLI reference.

The CLI is for CI, automation, and headless workflows. Everything you can do in the web UI, you can do from the terminal. Run qaclan <command> --help for the exhaustive flag list.

Auth gate

Five commands bypass authentication — login, logout, uninstall, serve, and the hidden _pw-install. Every other command requires a valid stored auth key; unauthenticated calls exit non-zero with a hint to run qaclan login.

Top-level

Project

Environment

Web — Feature

Web — Record

Records a new script via Playwright codegen. Launches a visible browser; when you close it, the captured Python is written to ~/.qaclan/scripts/, runtime-patched, and scanned for {{KEY}} placeholders.

Web — Script

Web — Suite

Web — Run

Execute a suite. --suite accepts a local id, cloud id, or exact suite name within the active project.

# staging smoke on tablet viewport, headless, stop on first failure
$ qaclan web run --suite Smoke --env staging \
    --browser firefox --resolution 1024x768 --headless --stop-on-fail

# all three engines in a loop
for b in chromium firefox webkit; do
  qaclan web run --suite "Full Regression" --browser $b --headless
done

Runs

qaclan runs is a hybrid — invoked without a subcommand it prints the list; the detail view lives under the sibling run group.

API (coming soon)

The api group is scaffolded but not implemented. Subcommands currently print a "coming soon" notice:

• qaclan api feature create|list|delete
• qaclan api suite create|list
• qaclan api run --suite <id> [--env <name>]

Pricing.

Free forever for solo QA — no limit on what you can test locally. Team dashboards and analytics on the Pro plan.

Feature comparison

Changelog.

Recent additions, newest first. Patch releases are folded into their nearest minor entry.