Skip to content

INSTALLATION.md

Latest commit

 

History

History
103 lines (65 loc) · 3.04 KB

INSTALLATION.md

File metadata and controls

103 lines (65 loc) · 3.04 KB
Raw

Installation Guide

Don't want to build from source? Download ContextUI for macOS, Windows, and Linux — free, no account required.

Prerequisites

  • Node.js 18+ (recommended: 20 LTS)
  • npm 9+ (comes with Node)
  • Git

Python is not required upfront — ContextUI can download and install Python automatically when a workflow needs it.

Quick Start

git clone https://github.com/contextui-desktop/contextui.git
cd contextui
npm install
npm run electron:dev

The app will open in development mode with hot-reload enabled.

Platform-Specific Notes

macOS

Install Xcode Command Line Tools (required for native module compilation):

xcode-select --install

If you encounter gyp errors during npm install, ensure the tools are properly installed.

Windows

Install Visual Studio Build Tools with the "Desktop development with C++" workload. This provides the MSVC compiler and Windows SDK needed for native modules.

Linux (Debian/Ubuntu)

sudo apt-get install build-essential libx11-dev libxkbfile-dev libsecret-1-dev

For RPM-based distros, install the equivalent -devel packages.

Building a Distributable

npm run electron:build

This uses electron-builder to produce platform-specific installers in the release/ directory:

  • macOS: .dmg
  • Windows: .exe (NSIS installer)
  • Linux: .deb

Python Setup

ContextUI manages Python automatically. When you open a workflow that needs a Python backend, the app will:

  1. Detect any existing Python installation on your system
  2. Download and install Python if needed (3.11, 3.12, or 3.13)
  3. Create and manage virtual environments per workflow
  4. Install required pip packages automatically

No manual Python setup is required. Virtual environments are stored in ~/ContextUI/<profile>/python_venvs/.

If you prefer to use your own Python installation, just ensure python3 (macOS/Linux) or python (Windows) is on your PATH and the app will detect it.

Troubleshooting

npm install fails with node-gyp errors

  • macOS: Run xcode-select --install
  • Windows: Install Visual Studio Build Tools with C++ workload
  • Linux: Install build-essential

Electron doesn't start

  • Delete node_modules and package-lock.json, then run npm install again
  • Ensure Node 18+ is active: node --version

Python venv issues

  • Check ~/ContextUI/<profile>/python_venvs/ for venv data — deleting stale venvs there can fix corruption
  • Look at the DevTools console (View > Toggle Developer Tools) for Python-related errors

Port 8800 already in use

The tool registry server runs on port 8800. If another process is using it:

lsof -i :8800  # macOS/Linux
netstat -ano | findstr :8800  # Windows

Kill the conflicting process or change the port in electron/tool-registry-server.cjs.

Build fails on Apple Silicon

Ensure you're using the arm64 version of Node.js, not the x64 version running under Rosetta.