SQLCipher Installation Guide

SQLCipher Installation Guide

Local Deep Research uses SQLCipher to provide encrypted databases for each user. This ensures that all user data, including API keys and research results, are encrypted at rest.

Installation by Platform

Ubuntu/Debian Linux

SQLCipher can be easily installed from the package manager:

sudo apt update
sudo apt install sqlcipher libsqlcipher-dev

After installing SQLCipher, install the project with PDM:

pdm install

PDM will automatically select the correct Python binding for your platform:

• x86_64 Linux: sqlcipher3-binary (pre-compiled wheel)
• ARM64 Linux: sqlcipher3 (builds from source)
• Other platforms: sqlcipher3

macOS

Install using Homebrew:

brew install sqlcipher

Then install the project with PDM:

# May need to set environment variables for building
export LDFLAGS="-L$(brew --prefix sqlcipher)/lib"
export CPPFLAGS="-I$(brew --prefix sqlcipher)/include"
pdm install

Windows

Windows installation is more complex and requires building from source:

1. Install Visual Studio 2015 or later (Community Edition works)
2. Install the "Desktop Development with C++" workload
3. Download SQLCipher source from https://github.com/sqlcipher/sqlcipher
4. Build using Visual Studio Native Tools Command Prompt

For easier installation on Windows, consider using WSL2 with Ubuntu.

Alternative: Using Docker

If you have difficulty installing SQLCipher, you can run Local Deep Research in a Docker container where SQLCipher is pre-installed:

FROM python:3.11-slim

# Install SQLCipher
RUN apt-get update && apt-get install -y \
    sqlcipher \
    libsqlcipher-dev \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Local Deep Research (SQLCipher binding selected automatically)
RUN pip install local-deep-research

CMD ["ldr", "serve"]

Verifying Installation

You can verify SQLCipher is installed correctly:

# Check command line tool
sqlcipher --version

# Test Python binding
python -c "from local_deep_research.database.sqlcipher_compat import get_sqlcipher_module; get_sqlcipher_module(); print('SQLCipher is installed!')"

Fallback Mode

If SQLCipher is not available, Local Deep Research will fall back to using regular SQLite databases. However, this means your data will not be encrypted at rest. A warning will be displayed when running without encryption.

Security Notes

• Each user's database is encrypted with their password
• There is no password recovery mechanism - if a user forgets their password, their data cannot be recovered
• The encryption uses SQLCipher's default settings with AES-256
• API keys and sensitive data are only stored in the encrypted user databases

Troubleshooting

Linux: "Package not found"

If your distribution doesn't have SQLCipher in its repositories, you may need to build from source or use a third-party repository.

macOS: "Library not loaded"

Make sure you've set the LDFLAGS and CPPFLAGS environment variables as shown above.

Windows: Build errors

Ensure you're using the Visual Studio Native Tools Command Prompt and have all required dependencies installed.

Python: "No module named sqlcipher3" or "pysqlcipher3"

Error variants:

• ModuleNotFoundError: No module named 'sqlcipher3'
• ModuleNotFoundError: No module named 'pysqlcipher3'

The project automatically selects the correct SQLCipher package based on your platform:

• x86_64 Linux: Uses sqlcipher3-binary (pre-compiled wheel)
• ARM64 Linux: Uses sqlcipher3 (builds from source with system SQLCipher)
• Other platforms: Uses sqlcipher3

Solution:

1. First, ensure you have the system SQLCipher library installed:

   # Debian/Ubuntu
   sudo apt-get install libsqlcipher-dev
   
   # macOS
   brew install sqlcipher
   

2. Then reinstall the Python package:

   # If using PDM (recommended)
   pdm install
   
   # If NOT using PDM (e.g., pip-only setup):
   pip install --force-reinstall sqlcipher3-binary  # x86_64 Linux
   pip install --force-reinstall sqlcipher3         # Other platforms
   

For Developers

To add SQLCipher to an automated installation script:

#!/bin/bash
# For Ubuntu/Debian
if command -v apt-get &> /dev/null; then
    sudo apt-get update
    sudo apt-get install -y sqlcipher libsqlcipher-dev
fi

# For macOS with Homebrew
if command -v brew &> /dev/null; then
    brew install sqlcipher
fi

# Install Python package (PDM handles platform-specific dependencies automatically)
pdm install