Fathom Server

Dashboard, API, and background services for Fathom — a multi-workspace vault system with search, activity tracking, rooms, and agent coordination.

Runs once, serves all workspaces. Per-workspace MCP tools are provided by fathom-mcp.

Architecture

┌──────────────────────────────────────────────┐
│  fathom-server (Python)                      │
│                                              │
│  React Dashboard ─── REST API ─── Services   │
│  (vault browser,    (Flask,      (indexer,   │
│   terminal,          :4243)       pings,     │
│   activation,                     crystal,   │
│   rooms,                          telegram,  │
│   telegram)                       access)    │
│                                              │
│  Workspace Registry + API Key Auth           │
└──────────────────┬───────────────────────────┘
                   │ HTTP localhost:4243
      ┌────────────┼──────────────┐
      ▼            ▼              ▼
┌──────────┐ ┌──────────┐  ┌──────────┐
│ ws: main │ │ ws: ns   │  │ ws: apps │
│ npx      │ │ npx      │  │ npx      │
│ fathom-  │ │ fathom-  │  │ fathom-  │
│ mcp      │ │ mcp      │  │ mcp      │
└──────────┘ └──────────┘  └──────────┘
 Claude inst. Claude inst.  Claude inst.

Requirements

• Python 3.11+
• Node.js 18+ (for frontend build and qmd)
• qmd — npm install -g @tobilu/qmd (powers search)
• tmux (for agent sessions and inter-workspace messaging)

Install

git clone https://github.com/myrakrusemark/fathom-vault.git
cd fathom-vault

# Install Python package + dependencies
pip install -e .              # editable install — includes CLI entry point
pip install -e '.[dev]'       # optional: adds pytest + ruff

# Build the frontend
cd frontend && npm install && npm run build && cd ..
cp -r frontend/dist/* fathom_server/static/

Setup

Run the setup command to create the data directory and generate an API key:

fathom-server setup           # interactive — prompts for confirmation
fathom-server setup -y        # non-interactive — just do it

This creates the data directory (see Data directory below) and generates an API key. The key is printed once — copy it, you'll need it when running npx fathom-mcp init in your project directories.

Run

fathom-server                  # start the server (default: 0.0.0.0:4243)
fathom-server --port 8080      # custom port
fathom-server --host 127.0.0.1 # bind to localhost only

Opens at http://localhost:4243. On startup the server:

1. Loads all registered workspaces
2. Starts persistent Claude sessions for each workspace (if configured)
3. Configures ping schedulers, background indexer, and crystal regeneration
4. Starts the Telegram bridge (if enabled)

Install as a system service

Register fathom-server as a systemd user service that starts on boot:

fathom-server install                          # install, enable, and start
fathom-server install --port 8080              # custom port
fathom-server install --data-dir /opt/fathom   # custom data directory
fathom-server install --no-start               # install and enable without starting

This writes a unit file to ~/.config/systemd/user/fathom-server.service, enables linger (so the service survives logout), and starts it.

Manage the service with standard systemd commands:

systemctl --user status fathom-server.service
systemctl --user restart fathom-server.service
journalctl --user -u fathom-server.service -f

To remove the service:

fathom-server uninstall

CLI reference

fathom-server                    Run the server (default)
fathom-server serve              Run the server (explicit)
  --host HOST                    Bind address (default: 0.0.0.0)
  --port PORT                    Port (default: 4243)

fathom-server setup              First-time setup (data dirs + API key)
  -y, --yes                      Skip confirmation prompt

fathom-server install            Install as a systemd user service
  --host HOST                    Bind address (default: 0.0.0.0)
  --port PORT                    Port (default: 4243)
  --data-dir DIR                 FATHOM_DATA_DIR override
  --working-dir DIR              WorkingDirectory for the service
  --no-start                     Install and enable without starting

fathom-server uninstall          Remove the systemd user service

Quick start — new workspace

# In your project directory:
npx fathom-mcp init

The init wizard prompts for server URL and API key, creates .fathom.json, registers the workspace with the server, and sets up Claude Code hooks. See fathom-mcp README for details.

You can also add workspaces via the dashboard at Settings > Workspaces.

Data directory

Runtime data (SQLite database, API key, vaults, Telegram assets) is stored outside the install directory:

Priority	Location
1. FATHOM_DATA_DIR env var	Wherever you point it
2. XDG_DATA_HOME/fathom-server	Follows XDG spec
3. ~/.local/share/fathom-server	Default fallback

For development, set FATHOM_DATA_DIR=./data in your .env file to keep data in the project directory.

Configuration

Environment variables (override defaults):

Variable	Default	Description
FATHOM_DATA_DIR	~/.local/share/fathom-server	Runtime data directory
FATHOM_PORT	4243	Server port
FATHOM_VAULT_DIR	(none)	Default vault directory

Server config — <data-dir>/server.json (auto-generated):

{
  "api_key": "fv_...",
  "auth_enabled": true
}

Per-workspace config — <project>/.fathom/settings.json (auto-created with defaults):

{
  "background_index": {
    "enabled": true,
    "interval_minutes": 15
  },
  "mcp": {
    "query_timeout_seconds": 120,
    "search_results": 10,
    "search_mode": "hybrid"
  },
  "activity": {
    "decay_halflife_days": 7,
    "recency_window_hours": 48,
    "show_heat_indicator": true
  },
  "crystal_regen": {
    "enabled": false,
    "interval_days": 7
  },
  "ping": {
    "routines": []
  }
}

API Authentication

All /api/* routes require a Bearer token when auth is enabled:

curl -H "Authorization: Bearer fv_abc123..." http://localhost:4243/api/workspaces

The dashboard is exempt (served from the same origin). Manage the API key from the dashboard at Settings > API Key & Auth.

HTTP API

Endpoint	Method	Description
/api/workspaces	GET	List all workspaces with status
/api/workspaces	POST	Register a workspace (name, path)
/api/workspaces/<name>	DELETE	Unregister a workspace
/api/vault	GET	Folder tree
/api/vault/folder/<path>	GET	List files with metadata and previews
/api/vault/file/<path>	GET/POST	Read/write files
/api/vault/append/<path>	POST	Append to files
/api/search	GET	Unified search (?q=...&mode=bm25|vector|hybrid)
/api/vault/links/<path>	GET	Forward/backlinks
/api/vault/activity	GET	Activity-scored file list
/api/room	GET	List all rooms
/api/room/<name>	GET/POST	Read/post room messages
/api/room/<name>/describe	POST	Set room description
/api/telegram/contacts	GET	List Telegram contacts
/api/telegram/messages/<id>	GET	Read messages (windowed)
/api/telegram/send/<id>	POST	Send a message
/api/telegram/send-image/<id>	POST	Send an image
/api/telegram/image/<id>	GET	Get message image (base64)
/api/telegram/status	GET	Bridge connection status
/api/settings	GET/POST	Settings management
/api/auth/status	GET	Auth status (masked key)
/api/auth/key	GET	Full API key
/api/auth/key/regenerate	POST	Generate new API key
/api/auth/toggle	POST	Enable/disable auth

All endpoints accept ?workspace= parameter. When omitted, they use the default workspace.

Search

Requires qmd with a collection matching the workspace name:

qmd collection add /path/to/project/vault --name my-project
qmd index my-project

The background indexer keeps it updated automatically.

Three search modes:

• bm25 — keyword search, fast, exact-match oriented
• vector — semantic/vector search, finds conceptually similar content
• hybrid — BM25 + vector + reranking, most thorough (default)

Dashboard

The React SPA at localhost:4243 provides:

• Vault browser — file tree with previews, heat indicators, frontmatter display
• Editor — markdown editing with frontmatter validation
• Terminal — WebSocket-connected tmux terminal for workspace sessions (Inbox mode for human workspaces)
• Activation — identity crystal viewer, ping scheduler controls
• Rooms — shared chatrooms for cross-workspace communication
• Telegram — contact list, message history, send/receive
• Settings — workspace management, API key management, per-workspace config

Project structure

fathom-vault/
├── fathom_server/               # Python package
│   ├── __init__.py              # Version from importlib.metadata
│   ├── app.py                   # Flask entry — routes, startup, CLI
│   ├── auth.py                  # API key generation + Bearer token middleware
│   ├── config.py                # Port, paths — configurable via env vars
│   ├── paths.py                 # XDG-compliant data directory resolution
│   ├── service.py               # systemd user service management
│   ├── static/                  # Built frontend (copied from frontend/dist/)
│   ├── routes/
│   │   ├── vault.py             # Vault CRUD, search, links, activity
│   │   ├── room.py              # Room chat endpoints
│   │   ├── settings.py          # Settings, workspace CRUD, auth management
│   │   ├── activation.py        # Identity crystal + activation
│   │   ├── telegram.py          # Telegram contacts, messages, images
│   │   └── terminal.py          # WebSocket terminal (tmux)
│   └── services/
│       ├── access.py            # SQLite activity tracking + scoring
│       ├── settings.py          # Settings persistence
│       ├── indexer.py           # Background vault indexing (qmd)
│       ├── links.py             # Wikilink parsing + backlinks
│       ├── crystallization.py   # Identity crystal synthesis
│       ├── crystal_scheduler.py # Scheduled crystal regen
│       ├── persistent_session.py# Workspace session management
│       ├── ping_scheduler.py    # Scheduled ping routines
│       ├── telegram_bridge.py   # Telegram bridge (Telethon)
│       ├── memento.py           # Memento SaaS API integration
│       └── vault.py             # Core vault file operations
├── frontend/                    # React SPA (Vite, Tailwind, DaisyUI, xterm.js)
├── fathom-mcp/                  # MCP tools npm package (see fathom-mcp/README.md)
├── tests/                       # pytest suite
├── pyproject.toml               # pip packaging + ruff/pytest config
└── .env                         # FATHOM_DATA_DIR for development

Test

pip install -e '.[dev]'
pytest

Pre-commit hooks run ruff (lint + format) and pytest:

pre-commit install
pre-commit run --all-files

License

MIT