Metadata-Version: 2.4
Name: brinqz-agent
Version: 0.2.2
Summary: Secure local execution agent for Brinqz Cloud
Author: Brinqz
Maintainer: Brinqz
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://brinqz.com
Project-URL: Documentation, https://github.com/ronnieparalejas/brinqz-agent#readme
Project-URL: Source, https://github.com/ronnieparalejas/brinqz-agent
Project-URL: Issues, https://github.com/ronnieparalejas/brinqz-agent/issues
Project-URL: Support, https://github.com/ronnieparalejas/brinqz-agent/issues
Project-URL: Brinqz Cloud, https://app.brinqz.com
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Requires-Python: <4,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: packaging>=24
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"

# 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:

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

For an isolated command-line installation, you can use
[pipx](https://pipx.pypa.io/):

```console
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:

```console
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, 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:

```console
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.

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:

```console
# 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 global `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:

```console
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.

```console
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](https://github.com/ronnieparalejas/brinqz-agent/issues).

## Development

```console
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.
