Installation | OpusAI

Distribution model: the website provides the OpusAI 1.2 source archive. The supplied run.sh creates and manages a local .venv.

Requirements

Linux
Python 3 with the venv module available
PySide6 6.7 or later, below major version 7, installed automatically from requirements.txt
Ollama installed and running locally
At least one local Ollama model for practical use; two models are optional if you want distinct Architect and Coder models

1. Download the source archive

Download OpusAI_1.2_SRC.zip from the Download page and extract it to a directory you control.

unzip OpusAI_1.2_SRC.zip
cd OpusAI_1.2

2. Make the launch helpers executable

chmod +x run.sh diagnose.sh

run.sh is the canonical source launcher. The included launch.sh exists as a compatibility wrapper and delegates to the canonical runner.

3. Verify Ollama

ollama --version
ollama list

OpusAI is designed around local Ollama models. PerformanceLab also uses the local Ollama HTTP endpoint, whose documented default is http://127.0.0.1:11434.

4. Launch OpusAI

./run.sh

On first launch, the runner creates .venv when needed, upgrades pip inside that environment, installs the suite requirements, then executes opusai.py.

What the runner changes

The runner confines Python package installation to the project's virtual environment. The source dependency file currently contains:

PySide6>=6.7,<7

Runtime storage

The integrated PerformanceLab uses namespaced storage beneath the OpusAI working directory:

config/performance_lab.json
data/performance_lab/benchmarks.json
reports/

These locations contain user-owned benchmark configuration, history and reports. The build script explicitly treats them as persistent state and avoids overwriting them when replacing a compiled application binary.

Optional source build

The project includes build.sh for producing a windowed, one-file PyInstaller application. The current website distribution is source-only, so building a binary is a local developer choice rather than a required installation step.

The build bundles the application icon, QSS, PerformanceLab benchmark module and report visualizer while leaving runtime benchmark state external beside the application.

Troubleshooting startup

Python venv is unavailable

Install the Python venv support package appropriate for your Linux distribution, then rerun ./run.sh.

Ollama models do not appear

Confirm Ollama is running and ollama list returns installed models. Pull the required model with Ollama before trying to assign it inside OpusAI.

PySide6 installation fails

Run the runner from a shell so pip errors are visible. Because the environment is local to the project, a failed package installation does not require modifying the system Python environment.