PuPu

Your AI, your way — beautifully simple.

     

PuPu is a lightweight, cross-platform desktop AI client that works with both local and cloud-hosted models. Whether you prefer running models on your own machine or connecting to providers like OpenAI and Anthropic, PuPu gives you a unified, elegant interface — your AI, your rules.

please star the repo if you find it interesting! ⭐

Features

🖥️ Multi-Platform Support

Runs natively on macOS, Windows, and Linux. Connect to local models via Ollama or use cloud providers like OpenAI and Anthropic — all from the same beautiful interface.

📂 Workspace & Local File Access

Attach a workspace and let AI read, edit, and manage your local files directly. PuPu bridges the gap between your AI conversations and your actual project files.

💬 Advanced Chat Management

Organize conversations with ease — pin, search, and manage multiple chat sessions. A refined chat experience designed for productivity, not clutter.

🔮 Roadmap

• Agent Builder — Create custom AI agents tailored to your workflows
• Agent Teams & Skills — Orchestrate multiple agents working together with specialized capabilities
• MCP Integration — Connect to the Model Context Protocol ecosystem for extended tool use and context sharing

Table of Contents

• Features
• For Users
  • App installation
• For Developers
  • Miso Setup
  • Local Setup
  • Deployment

For Users

App installation

Windows

• Download the .exe Windows installer here.
• Run the installer and follow the instructions.
• Once the installation is complete, you can find the app in the start menu.

Mac

• Download the .dmg Mac installer here.
• Open the downloaded file and drag the app to the Applications folder.
• Once the installation is complete, you can find the app in the Applications folder.

Linux

• Download the .deb or .AppImage file here.
• If you downloaded the .deb file, run the following command in the terminal:

sudo dpkg -i PuPu-0.1.0.deb

OR

sudo apt install ./PuPu-0.1.0.deb

• Ensuring Proper Sandbox Permissions: If you encounter an error message about sandbox permissions, you can run the following command:

sudo chown root:root /opt/PuPu/chrome-sandbox
sudo chmod 4755 /opt/PuPu/chrome-sandbox

For Developers

Miso Setup

PuPu starts a local Miso sidecar process when running the Electron app.

In development, PuPu looks for a valid Miso source in this order:

1. MISO_SOURCE_PATH (if set)
2. sibling folder ../miso

A valid Miso source must contain:

• miso/__init__.py
• miso/broth.py

Recommended setup:

1. Put the Miso repo next to PuPu:

# parent folder of PuPu
cd ..
git clone <your-miso-repo-url> miso
cd PuPu

2. Create a Python environment for the PuPu sidecar runtime:

python3 -m venv ./.venv
# Mac/Linux:
source ./.venv/bin/activate
# Windows: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.\.venv\Scripts\activate

pip install -r ./miso_runtime/server/requirements.txt

3. Install dependencies for your Miso repo (inside ../miso) based on that repo's instructions.

4. Configure Miso runtime environment variables (examples):

# optional if your miso repo is already at ../miso
export MISO_SOURCE_PATH=/absolute/path/to/miso

# optional override for Python executable used to launch miso sidecar
export MISO_PYTHON_BIN=/absolute/path/to/python

# optional (default: ollama)
export MISO_PROVIDER=ollama

# optional (provider-specific default will be used if omitted)
export MISO_MODEL=deepseek-r1:14b

# required when MISO_PROVIDER is openai or anthropic
export MISO_API_KEY=<your_api_key>
# or use provider-specific keys:
# export OPENAI_API_KEY=<your_api_key>
# export ANTHROPIC_API_KEY=<your_api_key>

Quick checks:

• If MISO_PROVIDER=ollama, ensure Ollama is running and the selected model is installed.
• Start PuPu with npm start and confirm Miso status in the app is ready.

Build packaged Miso sidecar (release)

For packaged apps, build a standalone miso-server binary first:

# macOS arm64
npm run build:miso:mac

Output path:

miso_runtime/dist/macos/miso-server

Notes:

• The script is miso_runtime/scripts/build_miso_server.sh.
• Default Miso source is ../miso. Override with MISO_SOURCE_PATH when needed.
• First run creates ./.venv-miso-build and installs build dependencies.
• First run needs network access to install pyinstaller and Python deps.
• If deps are already prepared, run with MISO_BUILD_SKIP_INSTALL=1.

Local Setup

• Install dependencies: To run the electron app locally, you need to install the dependencies by running the following command:

npm install

• Rebuild the Electron App: After installing the dependencies, you need to rebuild the electron app by running the following command:

npx electron-rebuild

• Run the Electron App: Once the dependencies are installed, you can run the app by running the following command:

npm start

• Browse built-in Mini UI components: After local startup, open the following page to preview available Mini UI native components:

http://localhost:2907/mini

Deployment

Build on the target OS host.

Common prerequisites

1. Make sure Miso source exists at ../miso, or set custom path:

export MISO_SOURCE_PATH=/absolute/path/to/miso

2. Install dependencies:

npm install

3. Optional cleanup before rebuilding:

# macOS / Linux
rm -rf dist

# Windows
Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue

macOS (arm64)

npm run build:electron:mac

Output files:

• dist/PuPu-<version>-arm64.dmg
• dist/mac-arm64/PuPu.app

Windows

Use Command Prompt or PowerShell as Administrator for Windows packaging.

Unsigned local build (recommended for development):

npm run pack:win:unsigned

Signed release build:

$env:WIN_CSC_LINK="C:\path\to\codesign.pfx"
$env:WIN_CSC_KEY_PASSWORD="your_password"
npm run pack:win

Output files:

• dist/PuPu Setup <version>.exe
• dist/win-unpacked/PuPu.exe

If you see Cannot create symbolic link : A required privilege is not held by the client, clear cache and rebuild in an Administrator shell:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\electron-builder\Cache\winCodeSign"
npm run pack:win

Linux

npm run build:electron:linux