Reading the repo

Opening the box…

How to set up SurfSense (MODSetter/SurfSense) · gitmanual

Assembly instructions

MODSetter/SurfSense

Air-gapped, privacy-focused, open-source NotebookLM alternative. AI agent that researches, transforms, and edits your documents. Join our Discord: https://discord.gg/ejRNvftDp9

Shell scripts#agent#agents#ai#notebooklm

Difficulty: Moderate
Time: 30 min or more
Stars: ★ 16,784
Activity: Updated this month
License: Apache-2.0
Open issues: 66
Got it running: Be the first
Looked up: 2 h ago

Saved setup from 2 h ago

Start here

Website ↗surfsense.comThe project's own site.

Will it work on my device?

Yes, it installs on your macOS

A ready-made macOS download is in the latest release.

Checking for

Download for macOS

v2.3.1 · 11/3/2026 ↗

SurfSense-arm64.dmg

dmg · Apple Silicon · 1118.3 MB · 53 downloads · best match

Download

Drag the app into Applications.

curl -LO "https://github.com/MODSetter/SurfSense/releases/download/v2.3.1/SurfSense-arm64.dmg"
open "SurfSense-arm64.dmg"

Install with a package manager

install script

curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh \| bash

Pipes a remote script into your shell. Read it before running.

From the README, exactly as the maintainers wrote it.

Did you get it running?

No reports for macOS yet.

Still stuck? Get a written guide

Claude reads the 11 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.

Parts list

1×Redis service

27× settings in .env

SURFSENSE_VERSION
SURFSENSE_VARIANT
SURFSENSE_PORT
SURFSENSE_PASSWORDsecret
SURFSENSE_AUTH
SURFSENSE_BIND
SURFSENSE_ALLOWED_HOSTS
SURFSENSE_TLS
SURFSENSE_DOMAIN
SURFSENSE_HTTPS_PORT
SURFSENSE_SECRETsecret
SURFSENSE_IMAGE
PORT
PLUGINS
REDIS_URL
SCRAPING_PROXY_PROVIDER
SCRAPING_CAPTCHA_PROVIDER
CRAWL_HEADED_XVFB_ENABLED
NEXT_PUBLIC_FASTAPI_BACKEND_URL
NEXT_PUBLIC_POSTHOG_KEYsecret
NEXT_PUBLIC_POSTHOG_HOST
DESKTOP_TELEMETRY_POSTHOG_KEYsecret
NEXT_PUBLIC_GLOBAL_ANNOUNCEMENT_ENABLED
NEXT_PUBLIC_GLOBAL_ANNOUNCEMENT_MESSAGE
NEXT_PUBLIC_GLOBAL_ANNOUNCEMENT_TONE
NEXT_PUBLIC_TOP_ANNOUNCEMENT_ENABLED
NEXT_PUBLIC_STRIPE_LICENSE_INDIVIDUAL_URL

Share this manual

Good to know

Has AGENTS.md — instructions for coding agents. You can open Claude Code (or another agent) in the cloned folder and ask it to do the setup for you.
Nested projects: backend/plugins/bundles/core/cli/pyproject.toml, backend/plugins/bundles/core/manifest/pyproject.toml, backend/plugins/bundles/core/sdk/pyproject.toml, backend/plugins/bundles/example/requirements.txt and 9 more

Files we read (11)

.github/workflows/build-audiocpp.yml

.github/workflows/build-opencv.yml

.github/workflows/build-sdcpp.yml

.github/workflows/desktop-tests.yml

.github/workflows/docker-tests.yml

.github/workflows/plugins-pull-request-checks.yml

CONTRIBUTING.md

README.md

backend/server/.env.example

docker/surfsense/.env.example

www/.env.example

Branch main · 4,966 files in the repo