Second Brain: A Self-Hosted AI Agent with Web UI, Module Store, and Widget Sandbox

What Second Brain Is and Who It Is For

Second Brain is a Python-based AI agent that runs on the user's own machine and provides a web browser interface at http://localhost:5174 by default. Unlike hosted AI assistants, it stores all conversations, configuration, and installed packages in a platform-specific data directory that never leaves the user's infrastructure.

The README describes its philosophy as inspired by the human brain: each iteration adds a new layer of capability, from simple question answering to file indexing, scheduled jobs, and multi-platform messaging. The kernel is intentionally thin; advanced capabilities such as knowledge base search over PDFs and audio files, self-maintaining memory stored as Markdown, Gmail integration, and a Telegram frontend are installed from a package store via the /packages install command.

The intended audience is developers and power users who want an AI agent they can fully control, extend, and inspect. The README also notes that Second Brain can be used directly from the terminal without the web UI, since the terminal interface is treated as a frontend identical in capability to the browser one.

Architecture: Kernel, Data Directory, and Package Store

Second Brain separates its architecture into two locations. The kernel is the cloned repository containing the application code, the web UI in frame_ui/, and the Python virtual environment. The data directory (DATA_DIR) is created on first run and holds configuration, the SQLite database, conversation history, installed packages, and the agent's workspace.

The data directory location depends on the operating system: on Windows it is %LOCALAPPDATA%\Second Brain\, on macOS it is ~/Library/Application Support/Second Brain/, and on Linux it is ~/.local/share/Second Brain/. The /locations command prints the exact paths in a running session.

Capabilities are added through the store at /packages install or the Settings page in the web UI. The README highlights bundle_knowledgebase (search over PDFs, Office files, images, and audio), bundle_memory (Markdown-based persistent memory), bundle_gmail (Gmail integration), and frontend_telegram (Telegram chat interface). Each store package declares its own additional Python dependencies, which the agent installs automatically.

The kernel requirements.txt is intentionally lean: watchdog for file watching, cron-descriptor and croniter for cron scheduling, and pytest plus pytest-xdist for the test suite.

Installing Second Brain and Running It for the First Time

The README requires Python 3.11+, git, and Node 20.19+ or 22.12+. The easiest path is to paste an installation prompt directly into Claude Code or a similar coding agent; the README provides a ready-to-use prompt for this. The manual installation steps are:

git clone https://github.com/henrydaum/second-brain
cd second-brain
python -m venv .venv

On macOS and Linux, activate the virtual environment with `source .venv/bin/activate`. On Windows, run `.venv\Scripts\activate`. Then install Python and Node dependencies:

pip install -r requirements.txt
cd frame_ui
npm install
cd ..
python main.py

The agent starts the web UI automatically. After a few seconds it prints the URL, typically http://localhost:5174. Once running, the /setup command installs the essentials bundle (file tools, shell, web search, subagents) and walks through connecting a model provider.

Connecting a Model and Running with Docker

Model connection is handled through /setup or directly via provider-specific commands. The README describes four paths: a ChatGPT plan with Codex device code authorization (no API key needed, requires enabling device code authorization in ChatGPT Settings under Security), an OpenRouter API key (which provides access to hundreds of models through one key), the standard API key flow for OpenAI, Anthropic, Gemini, or local models via Ollama, and any OpenAI-compatible endpoint.

For server or NAS deployments, Docker is supported via the included Dockerfile and docker-compose.yml. The compose file documents three modes:

docker compose run --rm second-brain

This starts an interactive REPL attached to the terminal. To run headless in the background:

docker compose up -d second-brain

Updates to the running instance are handled by /update, which pulls both the kernel repository and the UI together. The Docker image is designed so all user data lives in the sb-data volume outside the image, making updates non-destructive.

Widgets, Cron Jobs, and Self-Hosted Integrations

Second Brain supports widgets, which are HTML files the agent can write and run in a sandboxed iframe inside the web UI. The README uses running DOOM as a concrete demonstration of what the widget sandbox supports. Widgets are not restricted to games; any static HTML application the agent generates runs in the sandbox.

Scheduled tasks use cron expressions interpreted in the configured timezone. The croniter and cron-descriptor packages in requirements.txt handle parsing and human-readable description of cron schedules. Tasks can invoke any agent capability on a schedule.

File indexing (through bundle_knowledgebase) lets the agent search the user's own PDFs, Office files, images, and audio. The README notes this is a large download. The Tailscale integration mentioned in the README allows adding the web UI to a phone's home screen over a private network tunnel, giving mobile access to the local agent.

The README states that Second Brain performs higher than OpenClaw and Hermes on harness-bench, a benchmark measuring model-harness configuration effects across 106 sandboxed offline agent tasks. The evaluation repository and full results are linked from the README.

Limitations and Trade-offs

Second Brain is a single-person project with no organizational backing. The package store is a git repository; each package install pulls from a git ref and requires git to be installed. The kernel's test suite uses pytest-xdist to parallelize around 2,200 tests, but these tests cover the kernel only; package-level behavior is not covered in the core suite.

The web UI requires Node 20.19+ or 22.12+ and a completed npm install step. If npm install was skipped, the web UI silently fails to start; the README suggests checking web_ui.log in the data directory to diagnose this.

The default Docker bind port is to the host's loopback deliberately, which means the container's web UI is not reachable from the host by default without the SB_EXPOSE_HTTP environment variable and the included socat forwarder. The docker-compose.yml comments document this configuration in detail.

Because all data lives on the user's machine, there is no cloud sync, multi-device access, or backup built into the kernel. Multi-device access requires setting up Tailscale or an equivalent private network solution, as the README describes. The package store itself is a git repository; packages that do not have pre-built wheels for your Python version will fail to install, and the failure surface for store packages is broader than the lean kernel requirements.txt alone suggests.

Comparison with Claude Code and Other Terminal Agents

Claude Code from Anthropic is a terminal agent optimized for software engineering tasks: reading codebases, writing code, running tests, and managing git. It runs exclusively in the terminal, supports only Anthropic models, and has no web UI or package store. Its context management and permission system are mature and production-tested.

Second Brain is broader in scope. It has a web UI, supports any OpenAI-compatible model provider, handles scheduled tasks, supports mobile access via Tailscale, and extends through an installable package store. It is less focused on coding-specific workflows than Claude Code; the README describes it as an agent that handles file intelligence, workflow automation, and multi-modal messaging.

The MIT license on Second Brain permits any commercial use, modification, or redistribution. The README includes explicit uninstall instructions (delete the kernel folder and the DATA_DIR) with a note that no files are installed outside those two locations, except for the optional macOS deployment.

Editorial conclusion

Developers who want a locally running AI agent with a browser-accessible interface, pluggable capabilities, and full control over their data will find Second Brain the most self-contained option available in this category. The kernel requirements are deliberately lean (watchdog, croniter, cron-descriptor); most functionality arrives through the package store. Teams that need a pure coding assistant should compare Second Brain against Claude Code, which is a terminal-only agent focused on code; Second Brain is broader in scope but less focused on code-specific tools. Verify that Python 3.11+, Node 20.19+/22.12+, and git are installed before cloning, since the web UI build step requires npm and will fail silently without it.

Frequently asked questions

Official sources

1. henrydaum/second-brain on GitHub
2. Issues
3. License: MIT
4. Project website
5. README