Buy Me a Coffee

Cross-platform CLI for running QualityMax Playwright tests locally.

• Run as a daemon to poll and execute Playwright tests from QualityMax cloud
• Crawl websites behind firewalls, VPNs, and localhost with AI-powered discovery
• Capture browser cookies for authenticated test scenarios
• Authenticate via browser-based OAuth login
• Manage projects and credentials locally

Single binary, no runtime dependencies (Node.js/npm required only for test execution).

curl -fsSL https://raw.githubusercontent.com/Quality-Max/qmax-local-agent/main/install.sh | bash

This detects your OS and architecture, downloads the correct binary from GitHub Releases, and installs it to ~/.qmax/.

To install a specific version:

QMAX_VERSION=v3.0.0 curl -fsSL https://raw.githubusercontent.com/Quality-Max/qmax-local-agent/main/install.sh | bash

Download the latest release for your platform from Releases:

# macOS Apple Silicon
curl -fsSL -o qmax https://github.com/Quality-Max/qmax-local-agent/releases/latest/download/qmax-darwin-arm64
# macOS Intel
curl -fsSL -o qmax https://github.com/Quality-Max/qmax-local-agent/releases/latest/download/qmax-darwin-amd64
# Linux x86_64
curl -fsSL -o qmax https://github.com/Quality-Max/qmax-local-agent/releases/latest/download/qmax-linux-amd64
chmod +x qmax
sudo mv qmax /usr/local/bin/

Requires Go 1.23+:

git clone https://github.com/Quality-Max/qmax-local-agent.git
cd qmax-local-agent
make build

Cross-compile for all platforms:

make build-all

qmax login # Authenticate via browser
qmax projects # List your projects
qmax run --cloud-url https://app.qualitymax.io # Start the agent daemon

Authenticate with QualityMax via browser OAuth. Opens your browser and saves the token to ~/.qmax/config.json.

qmax login # Default (port 9876)
qmax login --port 8080 # Custom callback port
qmax login --api-url URL # Custom QualityMax URL

Start the agent daemon to poll for and execute test assignments and AI crawl discovery sessions.

qmax run --cloud-url https://app.qualitymax.io
qmax run --cloud-url https://app.qualitymax.io --registration-secret SECRET
qmax run --poll-interval 10 --heartbeat-interval 30

After the first successful registration, credentials are saved. Subsequent runs use saved values as defaults.

Backward compatibility — the old flag-based invocation still works:

qmax --cloud-url https://app.qualitymax.io --registration-secret SECRET

When running, the agent automatically polls for AI crawl discovery sessions alongside test assignments. When QualityMax assigns a crawl:

1. The agent launches a local Chrome browser (via chromedp)
2. Navigates to the target URL — including sites behind firewalls, VPNs, or localhost
3. Captures page snapshots (DOM elements, forms, selectors, screenshots)
4. Sends snapshots to the QualityMax server for LLM-powered navigation decisions
5. Executes the returned actions (click, fill, select) and repeats
6. When discovery completes, QualityMax generates Playwright test code from the captured flow

This enables AI-powered test generation for internal applications that the cloud cannot reach.

Set QMAX_CRAWL_HEADED=true to see the browser during crawl sessions (useful for debugging):

QMAX_CRAWL_HEADED=true qmax run --cloud-url https://app.qualitymax.io

Launch Chrome, navigate to a URL, wait for manual login, then capture all cookies and localStorage, and upload them as authentication data.

qmax capture --url https://example.com --project-id ID --name "Production Auth"
qmax capture --url https://example.com --project-id ID --name "Staging" --output cookies.json

Captures are stored as Playwright-compatible storage state JSON. Requires prior qmax login and Google Chrome installed.

List available projects.

qmax projects

Show current authentication and agent registration status.

qmax status

Print the saved OAuth token to stdout (useful for piping).

qmax token
qmax token | pbcopy # Copy to clipboard on macOS

Remove saved credentials.

qmax logout

Config is stored at ~/.qmax/config.json (mode 0600):

{
 "token": "eyJ...",
 "api_url": "https://app.qualitymax.io",
 "agent_id": "uuid",
 "api_key": "hex-key",
 "registration_secret": ""
}

See INSTALLATION.md for macOS LaunchAgent and Linux systemd setup instructions.

• All communication uses HTTPS/TLS
• Config file permissions are restricted to 0600 (owner read/write only)
• Config directory permissions are 0700
• HTTP response bodies are size-limited to prevent memory exhaustion
• Login callback validates request method and token length
• AI crawl sessions are authenticated via agent API key
• Crawl browser sessions have a 10-minute timeout
• HTTP retries use exponential backoff (3 attempts max)

Apache-2.0 -- see LICENSE.