Open Notebook

Running a fully local research stack

Start from the fully local example compose file, which adds Ollama and Speaches next to Open Notebook, then pull a chat model and an embedding model in Ollama and a Whisper model in Speaches. Register them under Manage, Models with Base URLs instead of API keys, assign them as defaults and add a test PDF. Confirm with network monitoring that no traffic leaves the host while a source is processed, chatted with and turned into a short podcast. Raise ESPERANTO_LLM_TIMEOUT and set OPEN_NOTEBOOK_WORKER_MAX_TASKS=1 if a single GPU struggles with parallel jobs.

Building a literature notebook from papers

Create a notebook per topic and upload papers in batches of up to 50, selecting Paper Analysis and Key Insights in the Process step so each paper gets structured insights. Enable embedding so vector search and Ask can reach them. For scanned PDFs or table-heavy papers, enable Docling and compare its extraction against the Simple engine on one difficult file before importing the rest. Then set papers to Insights only in notebook chat to keep each message small.

Answering cross-source questions with Ask

Use Ask when the answer is spread across many sources or notebooks. Limit it to the relevant notebooks, read the answer and open every cited item to verify the claim, since citations point to a whole source, note or insight rather than a page. When an answer looks thin, check whether the relevant sources were embedded; text search still finds non-embedded sources by exact terms. Save useful answers as notes so they become part of the notebook.

Turning research into a podcast episode

Edit a seeded episode profile and its speaker profile first: pick outline and transcript models, a text-to-speech model and voice IDs that exist for that model, because the seeded OpenAI voice names fail on other providers. Choose Summary or Full content per source, generate an episode and wait for the background job. If it fails, the episode card names the cause, such as an unsupported voice or truncated output; lower Max output tokens or the segment count and use Retry. Remember that the outline and transcript models see all selected content.

Automating ingestion through the REST API

Open /docs on the instance, create a notebook with POST /api/notebooks and send files or URLs to POST /api/sources with the bearer password if one is set. Poll GET /api/sources/{id}/status until processing completes, then query /api/search. Scripts that called the removed POST /api/commands/jobs endpoint now get 405 and must use the resource endpoints, as noted in the v1.15.1 release notes.

Putting an instance on a shared server

Before the first start, replace the public placeholder encryption key, set OPEN_NOTEBOOK_PASSWORD, bind ports 8502 and 5055 to 127.0.0.1 and publish them only through a reverse proxy with HTTPS, because the password travels in a header on every request. Set CORS_ORIGINS to the exact UI origin and keep SurrealDB unpublished with non-default credentials. Back up notebook_data and surreal_data before every upgrade, and store the encryption key apart from those backups, following the security guide.