Installation

Installation & Quick Start

This guide helps you install WorkPilot AI and run it for the first time.

---

✅ System requirements

Minimum configuration

Resource	Minimum	Recommended
OS	Windows 10+ / macOS 10.15+ / Ubuntu 20.04+	Latest versions
RAM	8 GB	16 GB
Storage	2 GB free	5 GB free
Network	Stable internet	—

Software dependencies (for source development)

• Node.js 20+ (CI builds on Node 22)
• Python 3.12+
• Git (initialized repository required on target projects)
• pnpm 8+
• Claude Code CLI (recommended) — pnpm add -g @anthropic-ai/claude-code

---

🔽 Option 1 — Desktop application (recommended)

The easiest method. Download the installer for your platform from the Releases page.

Windows

1. Download WorkPilot-AI-<version>-win32-x64.exe
2. Double-click the installer
3. Let Windows verify the signature then launch the app

macOS

• Apple Silicon (M1/M2/M3): WorkPilot-AI-<version>-darwin-arm64.dmg
• Intel: WorkPilot-AI-<version>-darwin-x64.dmg

Open the .dmg and drag the app into Applications.

Linux

• AppImage (universal): WorkPilot-AI-<version>-linux-x86_64.AppImage — make executable and run
• Debian/Ubuntu: .deb installable via sudo dpkg -i
• Flatpak: .flatpak

All releases ship with SHA256 checksums and VirusTotal scans.

---

🛠 Option 2 — From source (contributors)

# 1. Clone the repository
git clone https://github.com/krovomi/WorkPilot-AI.git
cd WorkPilot-AI

# 2. Install all dependencies (Node + Python auto)
pnpm install

# 3. Run in development mode (Electron + Vite HMR)
pnpm run dev

The script automatically creates the Python virtual environment and installs all dependencies.

Manual install (if automatic fails)

# Python backend
cd apps/backend
uv venv && uv pip install -r requirements.txt
# or: python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

# Electron frontend
cd ../frontend
pnpm install
pnpm run dev

---

🔑 AI provider configuration

On first launch, WorkPilot AI guides you through connecting at least one AI provider.

Claude (recommended — OAuth subscription)

claude
# Type: /login
# Follow the link in your browser

The OAuth token is saved in your OS keychain (macOS Keychain / Windows Credential Manager / Linux libsecret).

Supported providers

Provider	Auth method	Environment variable
Anthropic Claude	OAuth / API Key	ANTHROPIC_API_KEY
OpenAI	OAuth / API Key	OPENAI_API_KEY
Google Gemini	API Key	GOOGLE_API_KEY
Grok / xAI	API Key	XAI_API_KEY
Ollama (local)	Endpoint	OLLAMA_BASE_URL
Azure OpenAI	API Key + Endpoint	AZURE_OPENAI_*
GitHub Copilot	OAuth	via UI
OpenAI-compatible custom	API Key	via UI

👉 More details: AI Providers

---

📁 Prepare your project

WorkPilot AI operates on an initialized Git repository. Make sure your project contains:

my-project/
├── .git/                  # required
├── package.json           # or requirements.txt / Cargo.toml / go.mod…
└── …

Automatic stack detection recognizes common frameworks:

• Frontend: React, Vue, Angular, Svelte…
• Backend: Django, Flask, FastAPI, Express, NestJS…
• Languages: TypeScript, JavaScript, Python, Rust, Go, Java…
• Tools: Vite, Webpack, Cargo, Poetry, Maven, Gradle…
• Tests: Jest, Vitest, Pytest, Playwright, Cypress…

---

✔️ Verify installation

node --version       # v20 or higher
python --version     # 3.12 or higher
git --version
claude --version     # if Claude Code CLI is installed

In the app, open Settings → Diagnostics: all checks should be green.

---

❗ Quick troubleshooting

Problem	Solution
Node.js not found	Reinstall from nodejs.org with "Add to PATH"
Native modules (xterm, pty…)	cd apps/frontend && pnpm run rebuild
Python missing	Install Python 3.12+ and add to PATH
Claude token expired	claude then /login
Invalid API key	Check env vars in .env-files/.env
OAuth issue	Revoke in provider settings and re-authorize
Slow UI	Restart app, close other AI terminals

More? ➡️ Full troubleshooting

---

Next step

➡️ Your first project