INSTALLATION

Installation and environment

Logicytics is developed and exercised as a Windows-focused application. The v4 runtime has no required third-party Python dependency, but it deliberately uses a repository-local virtual environment so commands run with a known interpreter and do not depend on unrelated packages installed for another project.

Requirements

• A local checkout of this repository.
• Python 3.11 or later, available as python for the bootstrap command.
• Windows for live collector behavior and Windows integration checks.
• Enough trusted disk space for the configured output location and any ZIP package. Evidence output is not a cache; plan its storage accordingly.

Git is needed for the update and dev maintenance actions, but not for a normal already-checked-out collection run.

Bootstrap or repair the environment

From the repository root, run the installer:

python -m logicytics.cli.installer

It creates .venv if it does not exist, otherwise it reuses it. It also creates the root logicytics.yaml template if it is absent. To intentionally replace that template, use the explicit destructive configuration option:

python -m logicytics.cli.installer --overwrite-config

Back up or version-control a customized configuration before using --overwrite-config; it replaces the root template.

Run the supported interpreter

Every normal application command requires the managed environment. The most reliable form is the explicit interpreter path:

.\.venv\Scripts\python.exe -m logicytics preflight

You may activate the environment for an interactive shell:

.\.venv\Scripts\Activate.ps1
python -m logicytics preflight

If activation is blocked by PowerShell policy, do not weaken the policy just for this tool. Continue using .\.venv\Scripts\python.exe; it produces the same managed-environment execution.

Confirm the installation

Run the following in order:

python -m logicytics --help
python -m logicytics preflight

The first command verifies CLI invocation. The second verifies the selected collector sources and prerequisites without collecting evidence. Resolve any configuration or invalid-source result before attempting a plan or run.

Common environment mistakes

Symptom	Cause and correction
"Must run inside a virtual environment"	Use .\.venv\Scripts\python.exe for the normal CLI or activate via .\.venv\Scripts\Activate.ps1. Only the installer runs from the system interpreter.
python is not recognized	Install a supported Python version or invoke its known executable for the installer; after bootstrap use the local .venv path.
Activation is denied	Do not rely on activation. Use the explicit interpreter path.
A custom config disappeared	The installer was run with --overwrite-config; restore the backed-up configuration and preflight it before use.
Preflight finds invalid extension code	Correct or remove the named extension source. Extensions are intentionally not trusted just because their files exist.

For configuration fields and safe path rules, read Configuration. For collection scope after installation, continue to Getting Started.