lfnovo/open-notebook

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

mkdir open-notebook && cd open-notebook

docker run -d \
  --name open-notebook \
  -p 8502:8502 -p 5055:5055 \
  -v ./notebook_data:/app/data \
  -v ./surreal_data:/mydata \
  -e OPENAI_API_KEY=your_key_here \
  -e SURREAL_URL="ws://localhost:8000/rpc" \
  -e SURREAL_USER="root" \
  -e SURREAL_PASSWORD="root" \
  -e SURREAL_NAMESPACE="open_notebook" \
  -e SURREAL_DATABASE="production" \
  lfnovo/open_notebook:v1-latest-single

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

mkdir open-notebook && cd open-notebook

docker run -d \
  --name open-notebook \
  -p 8502:8502 -p 5055:5055 \
  -v ./notebook_data:/app/data \
  -v ./surreal_data:/mydata \
  -e OPENAI_API_KEY=your_key_here \
  -e API_URL=http://YOUR_SERVER_IP:5055 \
  -e SURREAL_URL="ws://localhost:8000/rpc" \
  -e SURREAL_USER="root" \
  -e SURREAL_PASSWORD="root" \
  -e SURREAL_NAMESPACE="open_notebook" \
  -e SURREAL_DATABASE="production" \
  lfnovo/open_notebook:v1-latest-single

⚠️ Critical Setup Notes:

Both ports are required:

• Port 8502: Web interface (what you see in your browser)
• Port 5055: API backend (required for the app to function)

API_URL must match how YOU access the server:

• ✅ Access via http://192.168.1.100:8502 → set API_URL=http://192.168.1.100:5055
• ✅ Access via http://myserver.local:8502 → set API_URL=http://myserver.local:5055
• ❌ Don’t use localhost for remote servers - it won’t work from other devices!

Using Docker Compose (Recommended for Easy Management)

Create a docker-compose.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

services:
  open_notebook:
    image: lfnovo/open_notebook:v1-latest-single
    # Or use: ghcr.io/lfnovo/open-notebook:v1-latest-single
    ports:
      - "8502:8502"  # Web UI
      - "5055:5055"  # API (required!)
    environment:
      - OPENAI_API_KEY=your_key_here
      # For remote access, uncomment and set your server IP/domain:
      # - API_URL=http://192.168.1.100:5055
      # Database connection (required for single-container)
      - SURREAL_URL=ws://localhost:8000/rpc
      - SURREAL_USER=root
      - SURREAL_PASSWORD=root
      - SURREAL_NAMESPACE=open_notebook
      - SURREAL_DATABASE=production
    volumes:
      - ./notebook_data:/app/data
      - ./surreal_data:/mydata
    restart: always

Start with: docker compose up -d

What gets created:

1
2
3
4

open-notebook/
├── docker-compose.yml # Your configuration
├── notebook_data/     # Your notebooks and research content
└── surreal_data/      # Database files

🆘 Quick Troubleshooting

How Open Notebook Works

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

┌─────────────────────────────────────────────────────────┐
│  Your Browser                                           │
│  Access: http://your-server-ip:8502                     │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
         ┌───────────────┐
         │   Port 8502   │  ← Next.js Frontend (what you see)
         │   Frontend    │
         └───────┬───────┘
                 │ needs to call ↓
                 ▼
         ┌───────────────┐
         │   Port 5055   │  ← FastAPI Backend (handles requests)
         │     API       │     This is why you need API_URL!
         └───────┬───────┘
                 │
                 ▼
         ┌───────────────┐
         │   SurrealDB   │  ← Database (internal, auto-configured)
         │   (Port 8000) │
         └───────────────┘

Key Point: Your browser loads the frontend from port 8502, but that frontend needs to know where to find the API (port 5055). When accessing remotely, you must tell it explicitly: API_URL=http://your-server-ip:5055

Star History

🛠️ Full Installation

For development or customization:

1
2
3

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

📖 Need Help?

• 🤖 AI Installation Assistant: We have a CustomGPT built to help you install Open Notebook - it will guide you through each step!
• New to Open Notebook? Start with our Getting Started Guide
• Need installation help? Check our Installation Guide
• Want to see it in action? Try our Quick Start Tutorial

Provider Support Matrix

Thanks to the Esperanto library, we support this providers out of the box!

*Supports LM Studio and any OpenAI-compatible endpoint

✨ Key Features

Core Capabilities

• 🔒 Privacy-First: Your data stays under your control - no cloud dependencies
• 🎯 Multi-Notebook Organization: Manage multiple research projects seamlessly
• 📚 Universal Content Support: PDFs, videos, audio, web pages, Office docs, and more
• 🤖 Multi-Model AI Support: 16+ providers including OpenAI, Anthropic, Ollama, Google, LM Studio, and more
• 🎙️ Professional Podcast Generation: Advanced multi-speaker podcasts with Episode Profiles
• 🔍 Intelligent Search: Full-text and vector search across all your content
• 💬 Context-Aware Chat: AI conversations powered by your research materials
• 📝 AI-Assisted Notes: Generate insights or write notes manually

Advanced Features

• ⚡ Reasoning Model Support: Full support for thinking models like DeepSeek-R1 and Qwen3
• 🔧 Content Transformations: Powerful customizable actions to summarize and extract insights
• 🌐 Comprehensive REST API: Full programmatic access for custom integrations
• 🔐 Optional Password Protection: Secure public deployments with authentication
• 📊 Fine-Grained Context Control: Choose exactly what to share with AI models
• 📎 Citations: Get answers with proper source citations

Three-Column Interface

1. Sources: Manage all your research materials
2. Notes: Create manual or AI-generated notes
3. Chat: Converse with AI using your content as context

📚 Documentation

Getting Started

• 📖 Introduction - Learn what Open Notebook offers
• ⚡ Quick Start - Get up and running in 5 minutes
• 🔧 Installation - Comprehensive setup guide
• 🎯 Your First Notebook - Step-by-step tutorial

User Guide

• 📱 Interface Overview - Understanding the layout
• 📚 Notebooks - Organizing your research
• 📄 Sources - Managing content types
• 📝 Notes - Creating and managing notes
• 💬 Chat - AI conversations
• 🔍 Search - Finding information

Advanced Topics

• 🎙️ Podcast Generation - Create professional podcasts
• 🔧 Content Transformations - Customize content processing
• 🤖 AI Models - AI model configuration
• 🔧 REST API Reference - Complete API documentation
• 🔐 Security - Password protection and privacy
• 🚀 Deployment - Complete deployment guides for all scenarios

(back to top)

🗺️ Roadmap

Upcoming Features

• Live Front-End Updates: Real-time UI updates for smoother experience
• Async Processing: Faster UI through asynchronous content processing
• Cross-Notebook Sources: Reuse research materials across projects
• Bookmark Integration: Connect with your favorite bookmarking apps

Recently Completed ✅

• Next.js Frontend: Modern React-based frontend with improved performance
• Comprehensive REST API: Full programmatic access to all functionality
• Multi-Model Support: 16+ AI providers including OpenAI, Anthropic, Ollama, LM Studio
• Advanced Podcast Generator: Professional multi-speaker podcasts with Episode Profiles
• Content Transformations: Powerful customizable actions for content processing
• Enhanced Citations: Improved layout and finer control for source citations
• Multiple Chat Sessions: Manage different conversations within notebooks

See the open issues for a full list of proposed features and known issues.

(back to top)

🤝 Community & Contributing

Join the Community

• 💬 Discord Server - Get help, share ideas, and connect with other users
• 🐛 GitHub Issues - Report bugs and request features
• ⭐ Star this repo - Show your support and help others discover Open Notebook

Contributing

We welcome contributions! We’re especially looking for help with:

• Frontend Development: Help improve our modern Next.js/React UI
• Testing & Bug Fixes: Make Open Notebook more robust
• Feature Development: Build the coolest research tool together
• Documentation: Improve guides and tutorials

Current Tech Stack: Python, FastAPI, Next.js, React, SurrealDB Future Roadmap: Real-time updates, enhanced async processing

See our Contributing Guide for detailed information on how to get started.

(back to top)

📄 License

Open Notebook is MIT licensed. See the LICENSE file for details.

📞 Contact

Luis Novo - @lfnovo

Community Support:

• 💬 Discord Server - Get help, share ideas, and connect with users
• 🐛 GitHub Issues - Report bugs and request features
• 🌐 Website - Learn more about the project

🙏 Acknowledgments

Open Notebook is built on the shoulders of amazing open-source projects:

• Podcast Creator - Advanced podcast generation capabilities
• Surreal Commands - Background job processing
• Content Core - Content processing and management
• Esperanto - Multi-provider AI model abstraction
• Docling - Document processing and parsing

(back to top)