Brinqz Agent

Brinqz Agent is the local command-line agent that runs approved Robot Framework test executions on your machine. Brinqz Cloud is its control plane: the Agent pairs with Cloud, receives execution work, runs it through the configured local test runtime, and returns approved results and artifacts.

Brinqz Agent is currently a Public Preview / Alpha release. It supports Windows, macOS, and Linux and requires Python 3.11 or newer (Python 4 is not supported).

Install and set up

Install or upgrade the Agent, then follow its guided setup:

python -m pip install --upgrade brinqz-agent
brinqz-agent setup

For an isolated command-line installation, you can use pipx:

pipx install brinqz-agent
brinqz-agent setup

The default control-plane URL is https://app.brinqz.com. For local development only, you can select a .test Cloud origin:

brinqz-agent setup --cloud-url http://app.brinqz.test

Setup guides you through Cloud pairing and capability choices, prepares an isolated Brinqz-managed execution runtime, registers per-user automatic startup, starts the Agent, installs the stable terminal-owning command launcher, and verifies Cloud health. Robot Framework is always enabled. Browser testing is recommended and defaults to Chromium; Firefox and WebKit are optional. Parallel execution with Pabot is optional.

It is safe to rerun brinqz-agent setup. A healthy matching runtime is reused. If repair or an upgrade is needed, setup builds and validates a replacement at its final path before selecting it, and retains the previous working runtime until activation succeeds.

Update

Pipx-managed installations can check for and apply stable Agent updates without pairing or choosing capabilities again:

brinqz-agent update --check
brinqz-agent update

update --check is non-mutating: it reports package, runtime, browser, Pabot, and startup status without repairing or installing anything. update preserves the Cloud connection, Runner and workspace identity, selected browsers, Pabot desired state, managed-runtime selection, and whether the background Agent was running. It updates the package through pipx, then reconciles the managed runtime and owned startup registration from those preserved choices.

The stable launcher lives outside the replaceable pipx environment. It forwards normal commands to the installed Agent. During an update it remains attached to the terminal while the old Agent exits, pipx replaces the package, the new Agent reconciles runtime/startup state, and the prior running or stopped state is restored. The command returns only after that complete operation succeeds or fails.

One-time migration from 0.3.1 and earlier

Released pipx-only versions cannot install the stable launcher retroactively. Upgrade once with pipx, then rerun setup using the upgraded Agent:

pipx upgrade brinqz-agent
brinqz-agent setup

On Windows, setup prepends the user-scoped Brinqz launcher directory to the user PATH; start a new terminal afterward. Pairing, Cloud URL, identity, runtime, browser/Pabot choices, worker settings, startup registration, and the previous background state are retained. Future brinqz-agent update operations are synchronous and self-contained.

Version 1 self-update officially supports pipx-managed Agent installations. The Agent deterministically verifies that pipx owns the exact running Agent environment before package replacement; other installation methods receive an actionable error instead of being modified automatically.

Setup choices and managed deployment

Normal users only need the two commands above. Managed deployments and CI can inspect advanced options with brinqz-agent setup --help. Common examples are:

# Recommended Chromium and Pabot capabilities
brinqz-agent setup --yes --recommended

# Explicit browsers and parallel execution
brinqz-agent setup --yes --browsers chromium,firefox --with-pabot

# Robot-only runtime without background registration
brinqz-agent setup --yes --robot-only --no-startup

Use --cloud-url to select a different approved Cloud origin. Rerun setup with --browsers or --with-pabot to change capabilities. Setup never installs project credentials or project secrets.

Execution runtime

The Agent package environment and execution environment remain separate. Setup creates a dedicated virtual environment under the user-scoped Agent data directory and never installs Robot Framework, Browser Library, browsers, or Pabot globally. It does not change the machine-wide PATH and does not require administrator or root privileges.

Browser setup prefers the official BrowserBatteries distribution, which avoids a separate Node.js installation on supported systems. On an unsupported system, setup can use an already-installed supported Node.js LTS runtime; it never silently installs Node.js or operating-system packages. If Linux browser system dependencies are missing, setup reports the requirement without automatically using sudo.

Use the following command to inspect the Agent configuration, selected runtime, and required local capabilities:

brinqz-agent doctor

Advanced users can keep a compatible external runtime with brinqz-agent runtime use <python-path>. Setup preserves a valid manually selected runtime; use --managed-runtime when deliberately switching back to Brinqz management.

Linux display behavior

Headless Robot and Browser setup works without DISPLAY. Headed browser execution requires a real logged-in graphical session and a valid DISPLAY or Wayland environment inherited by the Agent. The Agent does not fabricate display variables. A headed request without a display fails with a concise diagnostic. Some distributions require browser system libraries installed by an administrator; setup explains those requirements and does not elevate itself.

Background lifecycle

The background registration is per-user: Task Scheduler on Windows, a LaunchAgent on macOS, or a systemd user service on Linux.

brinqz-agent install
brinqz-agent status
brinqz-agent start
brinqz-agent stop
brinqz-agent restart
brinqz-agent uninstall

uninstall removes background startup registration but preserves pairing, managed runtimes, runtime selection, reports, and execution history. Remove the user-scoped Brinqz Agent data directory separately only when you deliberately want to delete those preserved files. brinqz-agent run is available as a foreground diagnostic mode.

Managed data locations are:

• Windows: %LOCALAPPDATA%\Brinqz Agent (runtime under runtime)
• macOS: ~/Library/Application Support/Brinqz Agent
• Linux: ${XDG_DATA_HOME:-~/.local/share}/brinqz-agent

Security model

The Agent initiates outbound communication to Brinqz Cloud and does not open inbound ports. Pairing establishes a local machine identity through Cloud's browser-approval flow, and approved machine credentials are stored in the user-scoped Agent configuration.

Project credentials are not entered or configured through Agent setup. An execution that requires an unavailable local secret is refused before process launch. The Agent executes prepared Robot Framework packages through a fixed Robot or Pabot invocation; it does not provide arbitrary remote shell execution.

Downloaded packages are authenticated, size and checksum verified, and safely extracted. Execution runs in a contained process boundary, and only approved report artifacts are returned to Cloud.

Public Preview limitations

This Alpha release is command-line only. It does not install Python, Node.js, Linux operating-system browser dependencies, or project secrets. It does not include a GUI or tray application, a native installer, or Runner-local project-secret storage. Interfaces and operational guidance may change before a stable release.

Support

Report problems and request support through the Brinqz Agent issue tracker.

Development

python -m venv .venv
# Activate .venv using your shell, then:
python -m pip install -e ".[dev]"
python -m pytest

The repository contains additional manual validation plans for maintainers.