lfnovo--open-notebook/docs/1-INSTALLATION/windows-native.md

# Open Notebook Windows Installation Guide (Native, No Docker)

This guide documents how to install and run [Open Notebook](https://github.com/lfnovo/open-notebook) on Windows **natively without Docker or WSL**.

## Who Is This For?

- **Windows ARM64 users** - Docker Desktop and WSL2 have limitations on ARM64
- **Users without Hyper-V** - Some Windows editions don't support Docker
- **Users who prefer native installs** - Simpler architecture, easier debugging

## What This Guide Covers

- Native Windows installation steps
- Critical configuration fixes for Windows
- Troubleshooting common issues
- Upgrade and maintenance scripts

## Prerequisites

| Software     | Installation                     | Required |
| ------------ | -------------------------------- | -------- |
| Git          | `winget install Git.Git`         | Yes      |
| Python 3.12+ | Via uv (installed automatically) | Yes      |
| Node.js 18+  | `winget install OpenJS.NodeJS`   | Yes      |
| uv           | `pip install uv`                 | Yes      |
| SurrealDB    | `scoop install surrealdb`        | Yes      |

## Quick Start

1. **Clone and setup:**

   ```bash
   cd %USERPROFILE%\Projects  # or your preferred location
   git clone https://github.com/lfnovo/open-notebook.git
   cd open-notebook
   uv sync
   cd frontend && npm install && cd ..
   ```

2. **Configure `.env`:**

   - Copy `.env.example` to `.env`

   - Add your API keys

   - **CRITICAL:** Change `SURREAL_URL` from `localhost` to `127.0.0.1`:

     ```env
     SURREAL_URL="ws://127.0.0.1:8000/rpc"
     ```

3. **Start the four services**, each in its own terminal, from the `open-notebook` folder.

   > Open Notebook does not ship a launcher script — start the services manually as below (or wrap them in your own `.bat`, see [Optional: one-click launcher](#optional-one-click-launcher)).

   ```batch
   REM Optional: point Open Notebook at a separate data folder (see Issue 4 below).
   REM Set this in each terminal before running, or skip to use ./data.
   set DATA_FOLDER=%USERPROFILE%\Projects\open-notebook-data

   REM Terminal 1 — SurrealDB
   surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:%DATA_FOLDER%\surrealdb

   REM Terminal 2 — API
   uv run --env-file .env run_api.py

   REM Terminal 3 — Worker (module form avoids the Windows "canonicalize" error, see Issue 3)
   set PYTHONPATH=%CD%
   uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands

   REM Terminal 4 — Frontend
   cd frontend && npm run dev
   ```

4. **Open the app:** http://127.0.0.1:3000

## Directory Structure (Recommended)

```
YourProjectsFolder\
├── open-notebook\           # Source code (git clone)
│   ├── .venv\               # Python virtual environment (created by uv)
│   ├── frontend\            # Next.js frontend
│   ├── commands\            # Worker command modules
│   └── .env                 # Your configuration
├── open-notebook-data\      # Data storage (SEPARATE from code!)
│   ├── surrealdb\           # Database files
│   ├── uploads\             # Uploaded documents
│   └── sqlite-db\           # LangGraph checkpoints
└── start-open-notebook.bat  # Optional launcher you create yourself (see below)
```

**Why separate data folder?** Prevents accidental data loss when updating/reinstalling code.

## Optional: one-click launcher

Open Notebook does not ship a launcher, but you can save the following as
`start-open-notebook.bat` (anywhere you like) to start all four services with a
double-click. Adjust `ROOT` and `DATA_ROOT` to match your setup.

```batch
@echo off
REM --- adjust these two paths ---
set ROOT=%USERPROFILE%\Projects\open-notebook
set DATA_ROOT=%USERPROFILE%\Projects\open-notebook-data

set DATA_FOLDER=%DATA_ROOT%
set PYTHONPATH=%ROOT%
cd /d %ROOT%

start "SurrealDB" surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:%DATA_ROOT%\surrealdb
start "API" cmd /k "uv run --env-file .env run_api.py"
start "Worker" cmd /k "uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands"
start "Frontend" cmd /k "cd /d %ROOT%\frontend && npm run dev"
```

Then open http://127.0.0.1:3000.

## Critical Windows Fixes

### Issue 1: Wrong Python Version

**Symptom:**

```
ModuleNotFoundError: No module named 'langgraph.checkpoint.sqlite'
```

Traceback shows system Python (e.g., `C:\Python314\`) instead of venv.

**Cause:** Windows may have multiple Python versions. The venv's `activate.bat` doesn't always override correctly.

**Solution:** Use `uv run` instead of direct python calls:

```batch
REM Wrong:
.venv\Scripts\python.exe run_api.py

REM Correct:
uv run python run_api.py
```

### Issue 2: Database Health Check Timeout

**Symptom:**

```
WARNING: Database health check timed out after 2 seconds
```

Frontend shows "Database is offline" even though SurrealDB is running.

**Cause:** `.env` uses `localhost` but SurrealDB binds to `127.0.0.1`.

**Solution:** In `.env`, change:

```env
# Wrong:
SURREAL_URL="ws://localhost:8000/rpc"

# Correct:
SURREAL_URL="ws://127.0.0.1:8000/rpc"
```

### Issue 3: Worker "Failed to canonicalize script path"

**Symptom:**

```
Failed to canonicalize script path
```

**Cause:** The `surreal-commands-worker.exe` can't find the Python `commands` module.

**Solution:** Use Python module invocation with PYTHONPATH:

```batch
set PYTHONPATH=%ROOT%
uv run --env-file .env python -m surreal_commands.cli.worker --import-modules commands
```

### Issue 4: DATA_FOLDER Path Parsing Error

**Symptom:**

```
warning: Failed to parse environment file .env at position X
```

**Cause:** `uv` can't parse Windows paths with backslashes in `.env`.

**Solution:** Keep `DATA_FOLDER` **commented out** in `.env`. Set it via batch file:

```batch
set DATA_FOLDER=C:\path\to\open-notebook-data
```

## Configuration Files

### Modifying `open_notebook/config.py`

The default `config.py` uses a hardcoded data path. Modify it to read from environment:

```python
import os

# ROOT DATA FOLDER - can be overridden via DATA_FOLDER environment variable
DATA_FOLDER = os.environ.get("DATA_FOLDER", "./data")

# Rest of file uses DATA_FOLDER...
```

### Required `.env` Settings

```env
# Database - MUST use 127.0.0.1!
SURREAL_URL="ws://127.0.0.1:8000/rpc"
SURREAL_USER="root"
SURREAL_PASSWORD="root"
SURREAL_NAMESPACE="open_notebook"
SURREAL_DATABASE="open_notebook"

# API Keys (uncomment and fill in)
OPENAI_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here
GOOGLE_API_KEY=your-key-here
```

## Available AI Models

Once running, add models in Settings. Common model names:

| Provider  | Models                                                       |
| --------- | ------------------------------------------------------------ |
| OpenAI    | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `text-embedding-3-small` |
| Anthropic | `claude-sonnet-4-20250514`, `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022` |
| Google    | `gemini-3.5-flash`, `gemini-2.5-flash`, `gemini-2.5-pro`     |
| DeepSeek  | `deepseek-chat`, `deepseek-reasoner`                         |

## Upgrading

When a new version is released:

```batch
cd open-notebook
git pull
uv sync
cd frontend && npm install && cd ..
```

Then restart all services. Your `.env` and data are preserved.

## Services & Ports

| Service   | Port | URL                        |
| --------- | ---- | -------------------------- |
| SurrealDB | 8000 | ws://127.0.0.1:8000        |
| API       | 5055 | http://127.0.0.1:5055/docs |
| Frontend  | 3000 | http://127.0.0.1:3000      |

## Troubleshooting

### Services won't start

- Check if ports are in use: `netstat -ano | findstr :8000`
- Kill existing processes: `taskkill /F /PID <pid>`

### Frontend can't connect to API

- Verify API is running: http://127.0.0.1:5055/docs
- Check `.env` has `API_URL=http://localhost:5055`

### Worker not processing commands

- Check Worker window for errors
- Verify PYTHONPATH is set in startup script

## Contributing

Found another Windows-specific issue? Please share your solution!

---

*Tested on Windows 11 ARM64 with Open Notebook v1.6.0*
*Created: January 2026*