Crucible icon CRUCIBLE
Documentation

Installation

Set up Crucible 1.2 from source on a Linux workstation using its included virtual-environment runner.

Distribution model: the website provides the Crucible 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 Crucible_1.2_SRC.zip from the Download page and extract it to a directory you control. 

unzip Crucible_1.2_SRC.zip
cd Crucible_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

Crucible 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 Crucible 

./run.sh

On first launch, the runner creates .venv when needed, upgrades pip inside that environment, installs the suite requirements, then executes crucible.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 Crucible 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 Crucible.

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.