Setup

Setup

Home | To Developer | Deployment | Architecture

This page covers the development setup only. User-facing installers and release downloads stay in the main README.md.

Prerequisites

• Node.js and npm
  • The repo does not currently pin a Node engine version.
  • JavaScript dependencies, including Electron 40.6.0, come from package.json and package-lock.json.
• Python 3.12.x
  • PuPu expects Python 3.12.x for the local Miso sidecar runtime.
  • The bootstrap scripts rebuild .venv or .venv-miso-build if the interpreter version is wrong.
• A local Miso source checkout
  • In development, PuPu resolves Miso from MISO_SOURCE_PATH first, then ../miso.
  • A valid Miso source must contain miso/__init__.py and miso/broth.py.
• Model access
  • Local-first development usually means Ollama.
  • Remote providers use MISO_API_KEY or provider-specific keys such as OPENAI_API_KEY or ANTHROPIC_API_KEY.

Python Environment Conventions

• Team standard Python version: 3.12
• Development virtualenv path: .venv/
• Release-side Miso build virtualenv path: .venv-miso-build/
• Legacy venv/ is not supported
• MISO_PYTHON_BIN, when set, must point to a Python 3.12.x interpreter

Recommended Repo Layout

parent-folder/
|- PuPu/
`- miso/

Clone the Miso repo next to PuPu unless you intentionally want to override it with MISO_SOURCE_PATH.

Bootstrap The Repos

macOS / Linux

cd ..
git clone <your-miso-repo-url> miso
cd miso
./scripts/init_python312_venv.sh

cd ../PuPu
./scripts/init_python312_venv.sh
npm install
npx electron-rebuild

Windows

cd ..
git clone <your-miso-repo-url> miso
cd .\miso
powershell -ExecutionPolicy Bypass -File .\scripts\init_python312_venv.ps1

cd ..\PuPu
powershell -ExecutionPolicy Bypass -File .\scripts\init_python312_venv.ps1
npm install
npx electron-rebuild

Environment Variables

These variables are the supported development inputs for the sidecar and its provider configuration.

# Optional when your Miso repo already lives at ../miso
export MISO_SOURCE_PATH=/absolute/path/to/miso

# Optional override for the Python executable PuPu uses to launch the sidecar
export MISO_PYTHON_BIN=/absolute/path/to/PuPu/.venv/bin/python

# Optional provider and default model
export MISO_PROVIDER=ollama
export MISO_MODEL=deepseek-r1:14b

# Required for remote providers
export MISO_API_KEY=<your_api_key>
# or provider-specific keys
export OPENAI_API_KEY=<your_api_key>
export ANTHROPIC_API_KEY=<your_api_key>

Windows PowerShell uses $env:NAME="value" instead of export.

Local Startup Flow

1. Install JavaScript dependencies with npm install.
2. Rebuild Electron native dependencies with npx electron-rebuild.
3. Start the app with npm start.
4. Wait for PuPu to launch the local Miso sidecar and for the app status to report ready.
5. Open http://localhost:2907/mini to browse built-in Mini UI components and showrooms.

Useful local commands:

npm start
npm run start:web
npm run electron:start
npm test

What PuPu Resolves At Startup

• The Electron main process starts ollama serve when available.
• The Electron main process then starts Miso:
  • Packaged app: uses a bundled miso-server binary when present
  • Development app: runs miso_runtime/server/main.py with Python 3.12.x
• The sidecar receives runtime values such as:
  • MISO_HOST=127.0.0.1
  • a selected MISO_PORT
  • a per-launch MISO_AUTH_TOKEN
  • MISO_DATA_DIR=<app userData>
  • MISO_PARENT_PID=<electron pid>

Quick Verification

• python --version inside both PuPu and Miso .venv environments should report Python 3.12.x.
• If MISO_PROVIDER=ollama, make sure Ollama is installed and running.
• If MISO_PROVIDER is openai or anthropic, make sure the matching API key is present.
• Start the app with npm start and confirm the Miso status becomes ready.
• Open /mini and verify the Mini UI demo page renders.

Common Failures

Python version mismatch

Symptoms:

• MISO_PYTHON_BIN must point to Python 3.12.x
• startup errors mentioning missing Python runtime
• .venv gets rebuilt on bootstrap

Fix:

• Recreate both PuPu and Miso .venv environments with the provided bootstrap scripts.

Invalid Miso source

Symptoms:

• Miso stays not_found
• errors mention Miso server entrypoint was not found
• build scripts reject MISO_SOURCE_PATH

Fix:

• Make sure Miso exists at ../miso or set MISO_SOURCE_PATH.
• Verify miso/__init__.py and miso/broth.py exist in that checkout.

Ollama is unavailable

Symptoms:

• local model flows fail
• Ollama status stays unavailable or errors after startup

Fix:

• Install Ollama and verify ollama serve can run on the host.
• Pull or select a model that matches MISO_MODEL.

Provider key is missing

Symptoms:

• remote provider requests fail at run time
• Miso asks for MISO_API_KEY or provider-specific keys

Fix:

• Set MISO_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY before launching PuPu.