open-notebook Documentation

An Open Source implementation of Notebook LM with more flexibility and features

36,752 stars TypeScript TypeScript 1 file Β· ~6,630 tokens #assistant#learning#note-taking#notebook#notes-app#self-learning
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy open-notebook on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name open-notebook -p 8000:8000 --restart always surrealdb/surrealdb:v2
Configured Services & Ports
βš™οΈ surrealdb
image: surrealdb/surrealdb:v2
πŸ”Œ Ports: 127.0.0.1:8000:8000
βš™οΈ open_notebook
image: build locally
πŸ”Œ Ports: 8502:8502, 5055:5055
docker-compose.yml
yaml (docker-compose.yml) 
services:
  surrealdb:
    image: surrealdb/surrealdb:v2
    volumes:
      - ./surreal_data:/mydata
    environment:
      - SURREAL_EXPERIMENTAL_GRAPHQL=true
    ports:
      # Localhost only β€” the database uses default credentials, so never
      # publish this port on 0.0.0.0
      - "127.0.0.1:8000:8000"
    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
    pull_policy: always
    user: root
    restart: always
  open_notebook:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8502:8502"
      - "5055:5055"
    env_file:
      - ./docker.env
    depends_on:
      - surrealdb
    volumes:
      - ./notebook_data:/app/data
    restart: always

1. Project Overview & Quickstart (lfnovo/open-notebook)

File: README.md

Forks
Stargazers
Issues
MIT License

In a world dominated by Artificial Intelligence, having the ability to think 🧠 and acquire new knowledge πŸ’‘, is a skill that should not be a privilege for a few, nor restricted to a single provider.

Open Notebook empowers you to:

  • πŸ”’ Control your data - Keep your research private and secure
  • πŸ€– Choose your AI models - Support for 18+ providers including OpenAI, Anthropic, Ollama, LM Studio, and more
  • πŸ“š Organize multi-modal content - PDFs, videos, audio, web pages, and more
  • πŸŽ™οΈ Generate professional podcasts - Advanced multi-speaker podcast generation
  • πŸ” Search intelligently - Full-text and vector search across all your content
  • πŸ’¬ Chat with context - AI conversations powered by your research
  • 🌐 Multi-language UI - English, Portuguese, Chinese (Simplified & Traditional), Japanese, Russian, and Bengali support

Learn more about our project at https://www.open-notebook.ai

πŸ†š Open Notebook vs Google Notebook LM

Feature Open Notebook Google Notebook LM Advantage
Privacy & Control Self-hosted, your data Google cloud only Complete data sovereignty
AI Provider Choice 18+ providers (OpenAI, Anthropic, Ollama, LM Studio, etc.) Google models only Flexibility and cost optimization
Podcast Speakers 1-4 speakers with custom profiles 2 speakers only Extreme flexibility
Content Transformations Custom and built-in Limited options Unlimited processing power
API Access Full REST API No API Complete automation
Deployment Docker, cloud, or local Google hosted only Deploy anywhere
Citations Basic references (will improve) Comprehensive with sources Research integrity
Customization Open source, fully customizable Closed system Unlimited extensibility
Cost Pay only for AI usage Free tier + Monthly subscription Transparent and controllable

Why Choose Open Notebook?

  • πŸ”’ Privacy First: Your sensitive research stays completely private
  • πŸ’° Cost Control: Choose cheaper AI providers or run locally with Ollama
  • πŸŽ™οΈ Better Podcasts: Full script control and multi-speaker flexibility vs limited 2-speaker deep-dive format
  • πŸ”§ Unlimited Customization: Modify, extend, and integrate as needed
  • 🌐 No Vendor Lock-in: Switch providers, deploy anywhere, own your data

Built With

Python Next.js React SurrealDB LangChain

πŸš€ Quick Start (2 Minutes)

Prerequisites

  • Docker Desktop installed
  • That's it! (API keys configured later in the UI)

Step 1: Get docker-compose.yml

Option A: Download directly

bash
curl -o docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/main/docker-compose.yml

Option B: Create the file manually
Copy this into a new file called docker-compose.yml:

text
/* Detailed source-code truncated for AI context efficiency. */

Step 2: Set Your Encryption Key

Edit docker-compose.yml and change this line:

yaml
- OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string

to any secret value (e.g., my-super-secret-key-123)

Step 3: Start Services

bash
docker compose up -d

Wait 15-20 seconds, then open: http://localhost:8502

Step 4: Configure AI Provider

  1. Go to Models and choose your provider (OpenAI, Anthropic, Google, etc.)
  2. Click + Add Configuration
  3. Paste your API key and other info as needed and click Add Configuration
  4. Click Test to test connection
  5. Click Sync Models and check models to include
  6. Under Default Model Assignments, click Auto-Assign Defaults or manually specify which models to use for what

Done! You're ready to create your first notebook.

Need an API key? Get one from:
OpenAI Β· Anthropic Β· Google Β· Groq (free tier)

Want free local AI? See examples/docker-compose-ollama.yml for Ollama setup

πŸ“š More Installation Options

πŸ“– Need Help?

Star History

Provider Support Matrix

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

Provider LLM Support Embedding Support Speech-to-Text Text-to-Speech
OpenAI βœ… βœ… βœ… βœ…
Anthropic βœ… ❌ ❌ ❌
Groq βœ… ❌ βœ… ❌
Google (GenAI) βœ… βœ… βœ… βœ…
Vertex AI βœ… βœ… ❌ βœ…
Ollama βœ… βœ… ❌ ❌
oMLX βœ… βœ… ❌ ❌
Perplexity βœ… ❌ ❌ ❌
ElevenLabs ❌ ❌ βœ… βœ…
Deepgram ❌ ❌ βœ… βœ…
Azure OpenAI βœ… βœ… βœ… βœ…
Mistral βœ… βœ… βœ… βœ…
DeepSeek βœ… ❌ ❌ ❌
Cohere βœ… βœ… ❌ ❌
Voyage ❌ βœ… ❌ ❌
xAI βœ… ❌ ❌ βœ…
OpenRouter βœ… βœ… βœ… βœ…
DashScope (Qwen) βœ… ❌ ❌ ❌
MiniMax βœ… ❌ ❌ ❌
Novita βœ… ❌ ❌ ❌
PayPerQ (PPQ) βœ… βœ… βœ… βœ…
OpenAI Compatible* βœ… βœ… βœ… βœ…

*Supports LM Studio and any OpenAI-compatible endpoint. Prefer the native oMLX provider for oMLX (Apple Silicon); see docs/5-CONFIGURATION/omlx.md.

✨ 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: 18+ 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

Podcast Feature

πŸ“š Documentation

Getting Started

User Guide

Advanced Topics

(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: 18+ 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

Explore GitHub Discussions for proposed features and product ideas, and open Issues for known bugs and approved work.

(back to top)

πŸ“– Need Help?

🀝 Community & Contributing

Join the Community

  • πŸ’¬ Discord Server - Get help, share ideas, and connect with other users
  • 𝕏 Follow @lfnovo on X - Project updates and news from the maintainer
  • πŸ’‘ GitHub Discussions - Ask questions and shape features, product direction, design, and architecture
  • πŸ› GitHub Issues - Report reproducible bugs and find approved work
  • ⭐ 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, including our guidelines for AI-assisted contributions. To understand what we're building (and what we'll say no to), read VISION.md.

(back to top)

πŸ“„ License

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

Community Support:

(back to top)

File: docs/index.md

Open Notebook Documentation

Welcome to Open Notebook - a privacy-focused AI research assistant. This documentation is organized for different needs.

🎯 Choose Your Path

I'm brand new

β†’ Start here: 0-START-HERE

  • Learn what Open Notebook is
  • Pick your setup path (OpenAI, cloud, local/Ollama)
  • 5-minute quick start

I need to install/deploy

β†’ Go here: 1-INSTALLATION

  • Multiple installation routes
  • Docker Compose (recommended)
  • From source (developers)
  • Single container (deprecated, see Docker Compose)

I want to understand how it works

β†’ Read this: 2-CORE-CONCEPTS

  • Mental models and architecture
  • How RAG (retrieval-augmented generation) works
  • Notebooks, sources, and notes explained
  • Chat vs. transformations vs. podcasts

I want to use it (tutorials)

β†’ Follow this: 3-USER-GUIDE

  • How to add sources (PDFs, URLs, audio, video)
  • Creating and organizing notes
  • Chat effectively with your research
  • Creating podcasts from research
  • Search techniques

I need to configure it

β†’ Check this: 5-CONFIGURATION

  • Choose and setup AI provider
  • API configuration
  • Database setup
  • Advanced tuning

I need provider-specific help

β†’ Go here: 4-AI-PROVIDERS

  • OpenAI, Anthropic, Google, Groq, Ollama, Azure
  • Model comparisons
  • Cost estimates
  • Setup paths

Something's not working

β†’ Troubleshoot: 6-TROUBLESHOOTING

  • Quick fixes (top 10 issues)
  • Installation problems
  • Connection issues
  • AI/chat problems
  • Content processing issues
  • Podcast problems

I want to contribute/develop

β†’ Read this: 7-DEVELOPMENT

  • Architecture and tech stack
  • Contributing guidelines
  • API reference
  • Testing

πŸ“Š Documentation Overview

By Section

0-START-HERE β€” Entry point

  • What is Open Notebook?
  • Quick start guides (3 routes)
  • First 5 minutes

1-INSTALLATION β€” Getting it running

  • Multiple installation routes
  • Docker Compose (recommended), from-source
  • Requirements and setup

2-CORE-CONCEPTS β€” Understanding the system

  • Notebooks, sources, notes hierarchy
  • RAG (retrieval-augmented generation)
  • Chat, transformations, podcasts
  • Context management

3-USER-GUIDE β€” Using features

  • Adding sources (all types)
  • Working with notes
  • Chat effectively
  • Creating podcasts
  • Searching (text and semantic)

4-AI-PROVIDERS β€” AI configuration

  • Provider comparison
  • Setup for each provider
  • Model recommendations
  • Cost estimates

5-CONFIGURATION β€” Complete reference

  • AI provider setup (detailed)
  • Database configuration
  • Server/API settings
  • Advanced tuning
  • Environment variables (complete reference)

6-TROUBLESHOOTING β€” Problem solving

  • Quick fixes (top 10)
  • Installation issues
  • Connection problems
  • AI/chat issues
  • Content processing
  • Podcast generation
  • Getting help

7-DEVELOPMENT β€” For contributors

  • Architecture
  • Contributing guidelines
  • API reference
  • Testing & development

πŸ” Find What You Need

By Problem Type

Installation & Setup

Using Open Notebook

Troubleshooting

Development

πŸ“š Reading Paths

Path 1: Complete Beginner (1-2 hours)

  1. 0-START-HERE/index.md β€” Understand what it is
  2. 0-START-HERE Quick Start β€” Set it up
  3. 2-CORE-CONCEPTS/index.md β€” Understand concepts
  4. 3-USER-GUIDE/index.md β€” Learn features

Result: Fully understand how to use Open Notebook

Path 2: Get Running Fast (15 minutes)

  1. 0-START-HERE β€” Pick your path
  2. Follow quick-start guide for your setup
  3. Start using!

Result: Running in 15 minutes, learn details later

Path 3: DevOps/Deployment (1-2 hours)

  1. 1-INSTALLATION β€” Understand routes
  2. 5-CONFIGURATION β€” Reference setup
  3. 7-DEVELOPMENT - Architecture β€” Understand system

Result: Ready to deploy to production

Path 4: Troubleshooting (5-30 minutes)

  1. 6-TROUBLESHOOTING/index.md β€” Identify problem
  2. Find specific guide
  3. Follow solutions

Result: Problem solved!

❓ Common Questions

Q: Where do I start?
A: β†’ 0-START-HERE β€” Choose your setup path

Q: How do I install it?
A: β†’ 1-INSTALLATION β€” Multiple routes available

Q: How do I use [feature]?
A: β†’ 3-USER-GUIDE β€” Step-by-step tutorials

Q: Why does [feature] work like that?
A: β†’ 2-CORE-CONCEPTS β€” Understand the mental model

Q: How do I configure [provider]?
A: β†’ 4-AI-PROVIDERS or 5-CONFIGURATION

Q: Something's broken, what do I do?
A: β†’ 6-TROUBLESHOOTING β€” Problem solver

Q: How does the system work?
A: β†’ 2-CORE-CONCEPTS β€” Architecture and concepts

Q: Can I contribute?
A: β†’ 7-DEVELOPMENT β€” Contributing guide

πŸ“– How This Documentation is Organized

Principles

  • Progressive Disclosure: Start simple, go deeper if needed
  • Multiple Entry Routes: Different paths for different users
  • High Signal-to-Noise: Focused content, no fluff
  • Step-by-Step: Clear instructions you can follow
  • Decision Trees: Help you pick the right path
  • Symptom-Based: Troubleshooting by what's broken

Structure

  • 0-START-HERE β€” Entry point (everyone starts here)
  • 1-INSTALLATION β€” Multiple setup routes
  • 2-CORE-CONCEPTS β€” Mental models (understand why)
  • 3-USER-GUIDE β€” How to use (step-by-step)
  • 4-AI-PROVIDERS β€” Provider guides
  • 5-CONFIGURATION β€” Reference material
  • 6-TROUBLESHOOTING β€” Problem solving
  • 7-DEVELOPMENT β€” For contributors

πŸš€ Quick Navigation

First Time?

β†’ START HERE

Just Want to Use It?

β†’ QUICK START (5 minutes)

Something Broken?

β†’ TROUBLESHOOTING

Full Reference?

β†’ CONFIGURATION

Developer?

β†’ DEVELOPMENT

πŸ“ž Getting Help

πŸ“ˆ Documentation Stats

  • 8 major sections
  • 35+ focused guides
  • ~80,000 words
  • Covers all features
  • Multiple entry paths
  • Progressive difficulty

🎯 Start Here

First time using Open Notebook?
β†’ Go to 0-START-HERE

Experienced, looking for specific help?
β†’ Use the navigation above to find your section

Something not working?
β†’ Go to TROUBLESHOOTING

Last updated: January 2026 | Open Notebook v1.2.4+

2. Official Technical Reference & Guides (lfnovo/docs)

Mintlify Starter Kit

Test

Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including

  • Guide pages
  • Navigation
  • Customizations
  • API Reference pages
  • Use of popular components

Development

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

text
npm i mintlify

Run the following command at the root of your documentation (where mint.json is)

text
mintlify dev

Publishing Changes

Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

Troubleshooting

  • Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
  • Page loads as a 404 - Make sure you are running in a folder with mint.json

Explore Related Technologies & Topics

View All 9,111+ Repositories β†’

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#assistant Browse assistant catalog β†’ #learning Browse learning catalog β†’ #note-taking Browse note-taking catalog β†’ #notebook Browse notebook catalog β†’ #notes-app Browse notes-app catalog β†’ #self-learning Browse self-learning catalog β†’ ⚑ MCP Servers Model Context Protocol β†’ 🧠 Agent Skills Prompt & rule files β†’ πŸ”Œ OpenAPI Specs REST & Swagger schemas β†’