nga 0.4.0

Local-first agentic browser automation factory

nga

Local-first agentic browser automation factory. This repository bootstraps the installed Factory: a pip-installable Python package that starts a local Control Room on a random loopback address and reports application and database health.

This is the first milestone of the Dark Factory MVP (spec: issue #1, ticket: issue #2). Per-user state lives in SQLite under %USERPROFILE%\.nga and never inside Git.

Requirements

• A supported Python installation (3.11 or newer) on Windows.
• An internet connection for the initial pip install of dependencies.

Install

After the package is published to PyPI, install it on a clean Windows user account:

py -3.11 -m pip install nga
nga install-skills

This installs the nga command and its Python dependencies into the active environment. The second command installs the nga skill in %USERPROFILE%\.agents\skills for all compatible agents on that user account.

For a local checkout, use:

py -3.11 -m pip install .
nga install-skills

Playwright's Python package is installed as a dependency. If the customer PC does not have Chrome or Edge, install the managed Chromium browser once:

py -3.11 -m playwright install chromium

Start the Factory

nga serve

The Factory:

• starts the Control Room and reports a random loopback address, for example Control Room: http://127.0.0.1:52341/ (loopback only);
• never binds to a LAN address;
• opens the reported address in the default browser (pass --no-open to suppress this);
• creates the per-user SQLite database at %USERPROFILE%\.nga\state.db on first start and keeps it valid across restarts.

Set NGA_HOME to redirect per-user state to another directory:

$env:NGA_HOME = "C:\path\to\state"; nga serve

The health view at http://127.0.0.1:<port>/ shows the running application version and the local database health.

Start an automation project

Put the approved analysis in a Markdown file, open Codex in the project folder, and invoke the installed skill:

$nga C:\path\to\analysis.md

The skill builds, tests, releases, trials, and hands over the automation. It continues until it needs credentials, access, a business decision, or protected approval. Internal delivery state stays in SQLite. nga status reports durable progress.

Release the package

Build and validate a wheel from the repository root:

py -3.11 -m pip install build twine
py -3.11 -m build
py -3.11 -m twine check dist\*

For the normal release path, create a GitHub Release. The repository's publish.yml workflow then builds and publishes the distributions with PyPI Trusted Publishing.

For a manual upload, run this only after the package has passed the checks:

py -3.11 -m twine upload dist\*

Focused tests

Fast startup and health behavior (no network required):

py -m pytest tests/test_state.py tests/test_control_room.py -v

Clean pip-install proof on an isolated venv (requires network to download dependencies, takes a few minutes):

py -m pytest tests/test_pip_install.py -m pip_install -v

Development environment (optional):

uv venv --python 3.11
uv pip install -p .venv -e ".[dev]"
.venv\Scripts\python -m pytest