Prerequisites for Running Open Notebook: Complete Setup Guide

You need Python 3.11+, Node.js 18+, Docker, Git, and the uv package manager installed, plus an AI provider API key or local LLM setup, to run the FastAPI backend, Next.js frontend, and SurrealDB database.

Open Notebook is a multi-component application comprising a Python FastAPI backend, a Next.js (React) frontend, and a SurrealDB database. Before you can launch the services, you must install a specific set of development tools and runtime dependencies that cover all three layers. The authoritative requirements are documented in docs/1-INSTALLATION/from-source.md within the repository.

Core Software Requirements

Python Runtime

You must have Python 3.11 or higher installed to execute the FastAPI backend, async workers, and all Python packages. The backend entry point at api/main.py relies on modern Python features available in 3.11+.

Node.js Environment

Node.js 18+ is required to power the Next.js frontend. The frontend/package.json defines the npm scripts and dependencies that run the development server via npm run dev.

Docker and Git

Docker (any recent version, including Docker Desktop or Engine) is essential for running the SurrealDB container used for storage and vector search. Git is needed to clone the repository and track changes.

uv Package Manager

The project uses uv as its recommended Python package manager. Install it via the official script:

curl -LsSf https://astral.sh/uv/install.sh | sh

According to the source code in docs/1-INSTALLATION/from-source.md, uv handles dependency resolution and virtual-environment creation significantly faster than traditional pip workflows.

AI Provider Configuration

You need access to an AI model through one of these methods:

• Cloud provider API key: OpenAI or Anthropic keys enable the built-in multi-provider AI features.
• Local LLM: If you prefer a free local model, you can skip cloud keys and use Ollama instead.

This configuration is stored in your environment file, which you create from the provided template at .env.example.

Step-by-Step Installation Checklist

Follow this sequence to prepare your environment:

1. Install core tools: Python 3.11+, Node 18+, Git, and Docker.

2. Install uv: Run the curl command above to get the Python package manager.

3. Clone the repository:

   git clone https://github.com/lfnovo/open-notebook.git
   cd open-notebook

4. Create a virtual environment and install dependencies:

   uv sync
   uv pip install python-magic   # optional dependency for file type detection
   

5. Start SurrealDB using the Makefile command:

   make database   # or: docker compose up surrealdb
   

6. Configure environment variables:

   cp .env.example .env

   Edit .env to set OPEN_NOTEBOOK_ENCRYPTION_KEY and any provider credentials.

7. Launch the API backend:

   make api   # spins up uvicorn on port 5055
   

8. Start the frontend:

   cd frontend && npm install && npm run dev

When successful, access the services at:

• Frontend: http://localhost:3000
• API documentation: http://localhost:5055/docs
• SurrealDB UI: http://localhost:8000

Alternative Setup with Conda

If you prefer Conda over uv for environment management, use this workflow:

conda create -n open-notebook python=3.11 -y
conda activate open-notebook
conda install -c conda-forge uv nodejs -y
uv sync

This approach still leverages uv for dependency synchronization but wraps the environment in a Conda-managed Python installation.

Key Configuration Files

File	Purpose
docs/1-INSTALLATION/from-source.md	Complete installation guide with prerequisites
Makefile	Task runner for commands like make api and make start-all
docker-compose.dev.yml	Development Docker composition including SurrealDB
.env.example	Template for required environment variables

Summary

• Python 3.11+, Node.js 18+, Docker, and Git are mandatory system-level prerequisites.
• uv is the recommended Python package manager for handling dependencies and virtual environments.
• You must configure an AI provider (OpenAI, Anthropic, or Ollama) by setting keys in your .env file.
• The Makefile provides convenient commands like make database and make api to start services.
• Once configured, the stack runs on ports 3000 (frontend), 5055 (API), and 8000 (SurrealDB).

Frequently Asked Questions

Do I need a GPU to run Open Notebook?

No. Open Notebook does not require a GPU for standard operation. You can use cloud-based AI providers (OpenAI or Anthropic) for language model inference, or run local models via Ollama on CPU-only machines, though GPU acceleration will improve local model performance.

Can I use Conda instead of uv for dependency management?

Yes. While uv is the recommended package manager, you can create a Conda environment with Python 3.11, install uv within that environment, and then run uv sync to install the project dependencies. This hybrid approach is documented in the docs/1-INSTALLATION/from-source.md guide.

What ports need to be available?

You must ensure ports 3000, 5055, and 8000 are free on your local machine. Port 3000 serves the Next.js frontend, 5055 hosts the FastAPI backend and documentation, and 8000 exposes the SurrealDB management interface.

Is a cloud AI API key mandatory?

No. A cloud API key is optional if you configure a local LLM using Ollama. The .env.example file supports both configurations, allowing you to set OLLAMA_BASE_URL for local inference or provider-specific keys (like OPENAI_API_KEY) for cloud services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}