How to use Open Notebook: install with Docker and chat with your sources

What you need before you install Open Notebook

You need Docker. On macOS and Windows, the README recommends Docker Desktop. On Linux, use Docker Engine with the Compose plugin.

You also need either an API key from an AI provider or a local model server such as Ollama. You add the key inside the app's UI, not in config files.

• Docker Desktop (macOS, Windows) or Docker Engine with the Compose plugin (Linux)
• An API key from an AI provider, or a local model server such as Ollama

Download the docker-compose.yml file

Create a folder and download the official compose file from the repository. The file runs two services: surrealdb, which is the database, and open_notebook, which provides the UI, API and background worker.

Set your encryption key before starting

Open docker-compose.yml and replace the placeholder value of OPEN_NOTEBOOK_ENCRYPTION_KEY with a long random secret you generate yourself. The README gives openssl rand -hex 32 as one example. This key encrypts the API keys you store, so keep it safe.

If other devices can reach the machine running Open Notebook, the README says the UI on port 8502 and the API on port 5055 are published on all network interfaces with no password by default. In that case, change the two port lines to bind to 127.0.0.1, or add an OPEN_NOTEBOOK_PASSWORD setting to the environment block, before you start the app.

• Replace change-me-to-a-secret-string with your own secret
• Limit ports to 127.0.0.1 if the machine is on a shared network
• Or set OPEN_NOTEBOOK_PASSWORD in the environment block

Start Open Notebook and open the UI

Start the services in the background with Docker Compose. The README says to wait about 30 seconds, then open the app in your browser.

• Open http://localhost:8502 in your browser

Connect an AI provider in the Models screen

Open Notebook does not ship with a model. You connect one from the sidebar. Providers that need a key, such as OpenAI, Anthropic or Google, take an API key. Local providers such as Ollama need a Base URL instead.

You need at least one Language model and one Embedding model. The README notes that Anthropic and Groq have no embedding models, so pair them with a provider that does.

• In the sidebar, open Models under Manage
• Find your provider and click Add Configuration
• Enter a name and your API key, or a Base URL for local providers, then click Add Configuration
• Click Test on the new configuration to check the connection
• Click Models, choose a Model Type, tick the models to add and click Add
• Under Default Model Assignments, click Auto-assign Defaults or pick models yourself

Create a notebook, add sources and chat

Once a model is assigned, create a notebook and add a source such as a PDF, video, audio file or web page. You can then search across your content and chat with the AI. The README says answers cite the sources, notes and insights they used.

For a fully local setup, the README points to a Local Quick Start that runs Ollama in Docker. The Docker Compose guide covers settings, backups, updates and remote access.

• Organize PDFs, videos, audio and web pages in notebooks
• Use full-text and vector search across your content
• Chat with the AI using your research as context