Run a development checkout

For contributors who already have the source repository. These commands describe the current checkout; they are not public desktop installer instructions.

Prerequisites

Use Python 3.12 and Node.js 22 for the development setup. You need the sibling misura-core, misura-frontend, faro, and packages/misura_methods directories from the same checkout. Linux analysis execution needs bwrap (bubblewrap) and prlimit. Install those with your operating system's package manager before running analyses.

Install engine dependencies

From the repository root:

cd misura-core
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e "../faro[research]"

On Windows, the environment's programs are under .venv\Scripts\. On macOS and Windows, also fetch the WebAssembly runtime from misura-core with node scripts/fetch_wasm_runtime.mjs. The available analysis packages differ by runtime; see How code runs.

Configure the model connection

Create a local, uncommitted misura-core/.env with the following variables. Use the endpoint, credential, and model identifier supplied by your service provider; the placeholders below are not working credentials.

LLM_BASE_URL=https://your-provider.example/v1
LLM_API_KEY=your-development-key
LLM_MODEL=your-model-id

The engine loads that file; variables already present in the process environment take precedence. It requires all three values. Development model requests use your configured service and may incur that service's charges. Keep credentials out of the assistant prompt, version control, screenshots, and shared diagnostics.

Start the app

From misura-frontend, install its dependencies and start the frontend and API together:

npm install
npm run dev

The launcher starts the local API on port 8000 by default and Next.js for the frontend. Open the frontend address printed in the terminal. The API health endpoint is http://127.0.0.1:8000/api/health. A successful health response confirms the engine is listening; it does not establish that the model, search, or report compilation services work.

To run the API separately, use .venv/bin/python scripts/dev_api.py from misura-core, and npm run dev:web from misura-frontend. Stop the processes with Ctrl+C.

Verify a first analysis

1. Open the app and confirm it connects to the engine.
2. Load the quickstart sample and verify its 24 rows and four columns.
3. Send the sample descriptive-analysis prompt. Confirm Python output and a figure appear.
4. Test literature search separately if you need it. Faro availability and network access affect search.
5. Test report compilation separately if you need it. Source builds need the document toolchain; a future packaged desktop build may bundle it.

Test the documented example without a model

From a checkout of the documentation website, use the product checkout's virtual-environment Python:

/path/to/misura-core/.venv/bin/python scripts/check-sample.py /path/to/misura

Replace both paths with your checkout paths. The check runs the downloadable sample through the real analysis tool in a temporary output directory, with file access limited to that sample. It checks the expected numbers, table, figure, and execution record, then removes its temporary outputs. It makes no model request and does not certify generated answers, connector access, or report compilation.

Startup problems

• Missing environment variables. Check all three LLM_* values and restart the API after configuration changes.
• Model authentication or endpoint error. Verify the provider URL, key permissions, and exact model ID with the provider. A healthy local API does not validate those values.
• Sandbox launch failure on Linux. Check bubblewrap and prlimit availability and read the execution error. Do not disable sandbox isolation to make an analysis work.
• Missing Python package. Install the requirements in the same virtual environment used by the API launcher. Reinstall after dependency changes.
• Port already in use. Stop the previous development process before starting another. Keep the frontend and API configuration in agreement.

Packaged desktop builds have a separate runtime, tool-fetch, frontend-build, and signing process documented in the desktop repository. Clean-machine installer verification is not established by this source setup guide.