Skip to content

Latest commit

 

History

History
334 lines (230 loc) · 8.56 KB

windows-setup.md

File metadata and controls

334 lines (230 loc) · 8.56 KB

Installing & Running OpenWhale on Windows

A step-by-step guide to get OpenWhale running on Windows 10/11.

🚀 One-Command Install (Recommended)

The fastest way to get started — the installer handles everything automatically:

Option A: PowerShell (Recommended)

Open PowerShell and run:

irm https://raw.githubusercontent.com/viralcode/openwhale/main/install.ps1 | iex

Or if you've already downloaded the repo:

powershell -ExecutionPolicy Bypass -File install.ps1

Option B: Batch File (Double-Click)

Download and double-click install.bat — or run from Command Prompt:

install.bat

Both scripts will:

  1. ✅ Check and install Git, Node.js 22+, and pnpm via winget
  2. ✅ Clone the repository to %USERPROFILE%\openwhale
  3. ✅ Run pnpm install and build native modules
  4. ✅ Create your .env config file
  5. ✅ Offer to start OpenWhale immediately

Tip

Run as Administrator for automatic prerequisite installation. Without admin, it will tell you what to install manually.

Manual Installation

Prerequisites

Requirement Version How to Get It
Node.js 22+ nodejs.org — use the Windows installer (.msi)
pnpm Latest npm install -g pnpm (after installing Node.js)
Git Latest git-scm.com — use the Windows installer

Tip

Use Windows Terminal or PowerShell instead of the legacy Command Prompt for the best experience.

Optional (for full feature support)

Tool Purpose How to Get It
Python 3.10+ Code execution tool python.org — check "Add to PATH" during install
FFmpeg Camera, screen recording, media tools winget install ffmpeg or ffmpeg.org
Docker Desktop Container management docker.com
Visual Studio Build Tools Native module compilation npm install -g windows-build-tools or install from visualstudio.microsoft.com

Step 1: Install Node.js

  1. Download the LTS installer from nodejs.org (v22 or later)
  2. Run the .msi installer — accept the defaults
  3. Important: Check the box for "Automatically install the necessary tools" if prompted (this installs Python and build tools)
  4. Verify the installation:
node -v    # Should show v22.x.x or higher
npm -v     # Should show 10.x.x or higher

Step 2: Install pnpm and Git

# Install pnpm globally
npm install -g pnpm

# Verify pnpm
pnpm -v

# If Git isn't installed, download from https://git-scm.com/download/win
git --version

Step 3: Clone and Install OpenWhale

# Clone the repository
git clone https://github.com/viralcode/openwhale.git

# Navigate into the project
cd openwhale

# Install dependencies (always use pnpm, not npm!)
pnpm install

# Allow native modules to build (select all when prompted)
pnpm approve-builds

Important

If pnpm approve-builds fails with compilation errors, you likely need Visual Studio Build Tools. Run:

npm install -g windows-build-tools

Then re-run pnpm install and pnpm approve-builds.

Step 4: Configure Environment

# Copy the example environment file
copy .env.example .env

Edit .env in your preferred editor (Notepad, VS Code, etc.) and add at least one AI provider key:

ANTHROPIC_API_KEY=your-key-here
# OR
OPENAI_API_KEY=your-key-here
# OR
GOOGLE_API_KEY=your-key-here

Tip

Most configuration can be done through the web dashboard after first launch — you don't need to edit .env for everything.

Step 5: Start OpenWhale

pnpm run dev

You should see output like:

🐋 OpenWhale server running at http://localhost:7777
📊 Dashboard: http://localhost:7777/dashboard

Open your browser to http://localhost:7777/dashboard.

Step 6: First-Time Setup

  1. Log in with the default credentials:
    • Username: admin
    • Password: admin
  2. Go to Settings → Providers to add your AI API keys
  3. Configure messaging channels and skills as needed

Warning

Change the default password immediately after first login!

Windows-Specific Notes

What Works on Windows

Feature Status Notes
Web Dashboard ✅ Full support
All AI Providers ✅ Full support
Shell Execution ✅ Uses cmd.exe PowerShell commands work too
Code Execution ✅ Python & JS Ensure Python is in PATH
Browser Automation ✅ Playwright + BrowserOS
File Operations ✅ Full support
WhatsApp / Telegram / Discord / Slack ✅ Full support
Twitter/X ✅ Full support
Camera & Screenshot ✅ Uses ffmpeg Requires FFmpeg in PATH
Screen Recording ✅ Uses ffmpeg Requires FFmpeg in PATH
Clipboard ✅ Uses clip.exe / powershell
Docker Tools ✅ Full support Requires Docker Desktop
Daemon (auto-start) ✅ Uses Startup folder pnpm run cli daemon install
Memory & Vector Search ✅ Full support

What Does NOT Work on Windows

Feature Reason
iMessage macOS only — requires Apple Messages.app
Apple Notes / Reminders macOS only — requires AppleScript
Apple Shortcuts macOS only
macOS Menu Bar App macOS only — SwiftUI native app

Running as a Background Service

OpenWhale can auto-start with Windows using the Startup folder:

# Install as a startup service
pnpm run cli daemon install

# Check daemon status
pnpm run cli daemon status

# Remove from startup
pnpm run cli daemon uninstall

Docker on Windows

If you prefer running OpenWhale in Docker:

# Make sure Docker Desktop is running

# Build and start
docker-compose up -d

# Verify it's running
curl http://localhost:7777/health

# Stop
docker-compose down

Troubleshooting

better-sqlite3 build errors

# Install build tools
npm install -g windows-build-tools

# Clean and reinstall
rmdir /s /q node_modules
del pnpm-lock.yaml
pnpm install
pnpm approve-builds

ENOENT: python or node-gyp errors

Ensure Python is installed and in your PATH:

python --version   # Should show 3.10+

If not found, reinstall Python from python.org and check "Add Python to PATH".

Port already in use

# Find what's using port 7777
netstat -ano | findstr :7777

# Kill the process (replace <PID> with the actual process ID)
taskkill /PID <PID> /F

PowerShell execution policy errors

If you see "running scripts is disabled on this system" when installing pnpm or running the installer:

Fix 1: Change the execution policy (recommended — run once, permanent fix):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then retry your command (e.g. npm install -g pnpm).

Fix 2: Bypass for current session only (no admin needed):

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
npm install -g pnpm

Fix 3: Skip pnpm scripts entirely — use corepack instead (built into Node 22+):

corepack enable
corepack prepare pnpm@latest --activate
pnpm -v   # verify it works

Fix 4: Use the batch file installer instead:

If PowerShell is giving you trouble, use install.bat instead — batch files are not affected by the execution policy:

install.bat

Tip

The install.ps1 script tries to handle this automatically by using corepack first. If you still hit issues, apply Fix 1 above and re-run the script.

FFmpeg not found

Install via winget:

winget install ffmpeg

Or download from ffmpeg.org, extract, and add the bin folder to your system PATH.

Next Steps