🔌 Offline & Air-Gapped Deployment

This umbrella tracks work to make Open Notebook fully functional without internet access — critical for privacy-focused users and secure environments.

Why This Matters

Many users choose Open Notebook specifically for privacy and data sovereignty:

• Security-conscious organizations running in isolated networks
• Researchers working with sensitive data
• Users in low-connectivity areas who need reliable local operation
• Privacy advocates who want zero external calls

Currently, Open Notebook requires internet access for certain operations. This umbrella tracks fixing that.

Current Blockers

1. Tiktoken Downloads (~Easy)

Issue: The tiktoken library downloads tokenizer files on first use.

Solution: Pre-cache tokenizer files in the Docker image.

# During build, pre-download:
import tiktoken
tiktoken.get_encoding("cl100k_base")
tiktoken.get_encoding("p50k_base")
# etc.

Status: Well understood, needs implementation.

2. Docker First-Boot Dependencies (~Medium)

Issue: Docker container tries to download Python packages on first startup (#265).

Solution: Ensure all dependencies are baked into the image, no runtime downloads.

Investigation needed: Why is virtualenv being downloaded at runtime?

3. Content Extraction (#264) (~Medium)

Issue: Content extraction may require external services.

Proposed solution: Support local extraction via Apache Tika or similar.

Status: Needs architecture decision — is this in scope for v1?

Issues Being Tracked

Core

• Enable use without internet access (remove tiktoken dependency) #264 — Enable use without internet access (remove tiktoken dependency)
• [Install]: Install a dockerized open-notebook instance with no internet connection #265 — Docker install with no internet connection

Future (out of scope for now)

• Local content extraction (Apache Tika integration)

How to Contribute

Tiktoken Caching (Good First Issue)

Difficulty: Easy | Skills: Python, Docker

1. Identify all tiktoken encodings used by Open Notebook
2. Add pre-download step to Dockerfile
3. Test in air-gapped environment
4. Submit PR

Docker Dependencies Investigation

Difficulty: Medium | Skills: Docker, Python packaging

1. Reproduce the issue from [Install]: Install a dockerized open-notebook instance with no internet connection #265
2. Identify what triggers runtime downloads
3. Fix the Dockerfile to include all dependencies
4. Test in isolated network
5. Submit PR

Getting Started

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

# Test current offline behavior
docker build -t open-notebook-test .
docker network create --internal isolated-net
docker run --network isolated-net open-notebook-test
# Observe what fails

Success Criteria

• Docker container starts without any network access
• All core features work offline (with local LLM like Ollama)
• Documentation updated with air-gapped deployment guide

References

• tiktoken caching docs
• Docker multi-stage builds

Maintainer: @lfnovo

Looking for contributors! Comment below to claim a task.