FileDepot

Bring people, files, and knowledge together.

FileDepot is a self-hosted file storage, sync, collaboration, and AI search platform maintained at cdburgess75/FileDepot. It provides a Docker-based server distribution, synchronization daemon, command-line tools, browser UI branding, admin smoke tests, and an AI search sidecar for permission-scoped file search and retrieval-augmented answers.

Current FileDepot version: VIII.001

Highlights

• Self-hosted FileDepot server deployment with Docker Compose.
• File synchronization daemon and command-line tools.
• File Depot terminology and FileDepot branding applied to the live web UI.
• HTTPS support, including Caddy internal TLS for IP-based test servers.
• Server smoke tests and doctor/repair tooling.
• AI search across accessible FileDepot files.
• Retrieval-augmented FileDepot answers with clickable references.
• Optional general AI answers clearly separated from private FileDepot answers.
• Seven-day answer caching to reduce token usage.
• Secret redaction controls before sending retrieved passages to an external AI provider.
• Browser-local AI search history grouped by Today, Yesterday, Last week, and Older.
• Compiled knowledge foundation for durable file summaries and future large-scale retrieval.
• Admin configuration groundwork for read-only external sources such as SMB, NTFS, and mounted folders.

Quick Server Install

For a fresh Linux server with Docker, set your hostname, admin login, and run the installer:

sudo FILEDEPOT_HOSTNAME=depot.example.com \
  FILEDEPOT_PROTOCOL=https \
  FILEDEPOT_ADMIN_EMAIL=admin@example.com \
  FILEDEPOT_ADMIN_PASSWORD='change-this-password' \
  scripts/install-filedepot-server.sh

For a LAN-only test install, use the server IP:

sudo FILEDEPOT_HOSTNAME=192.168.1.50 \
  FILEDEPOT_PROTOCOL=https \
  FILEDEPOT_ADMIN_EMAIL=admin@example.com \
  FILEDEPOT_ADMIN_PASSWORD='change-this-password' \
  scripts/install-filedepot-server.sh

Open the deployed server with:

https://your-hostname-or-ip

See docs/server-install.md for the full server guide.

After install, prove the server is healthy in one command:

sudo /opt/filedepot/smoke-test-filedepot-server.sh

For a fuller check or repair pass:

sudo /opt/filedepot/filedepot-doctor.sh
sudo /opt/filedepot/filedepot-doctor.sh --repair

Server Operations

The installer creates a working FileDepot server, starts services, applies branding, enables the AI search sidecar by default, and installs operational scripts into /opt/filedepot.

The installer is safe to rerun. On an existing server it repairs compose settings, keeps existing secrets, reapplies branding, restarts services, and preserves user data.

Reapply the FileDepot UI treatment after code-only updates:

sudo scripts/apply-filedepot-server-branding.sh

Force an existing install to HTTPS:

sudo scripts/set-filedepot-server-https.sh

Create a server backup:

sudo /opt/filedepot/filedepot-backup.sh

Restore from a backup archive:

sudo /opt/filedepot/filedepot-restore.sh /opt/filedepot-backups/filedepot-backup-YYYYmmdd-HHMMSS.tar.gz

Create a release tag after the repo is clean:

scripts/create-filedepot-release.sh VIII.002

Build the FileDepot server image scaffold:

docker build -f docker/filedepot-server/Dockerfile -t filedepot-server:local .

Branding And UI

FileDepot uses three canonical brand assets:

• filedepot_app_icon.png
• filedepot_wordmark.png
• filedepot_favicon.png

The branding script applies the official logo assets, login background, blue UI accents, dark-mode readability fixes, help-page cleanup, About dialog, AI search wording, File Depots terminology, Wiki hiding, captcha cleanup, and admin version display.

User-facing terminology is moving toward:

• File Depots for the list of storage areas.
• Personal for the default personal depot.
• Create Depot, Depot history, Delete Depot, and Depot settings.
• AI search files for the AI search entry point.

Some internal compatibility names remain while the project transitions safely.

AI Search

FileDepot AI search runs as a sidecar under services/ai-search/. It indexes files the signed-in user can access, returns ranked matching passages, and can generate grounded answers from those passages.

The current AI flow is:

Accessible files -> extracted passages -> keyword + vector retrieval -> cached answer -> cited UI

Search still works without an external AI provider. Provider-generated answers are an enhancement, not a requirement.

To enable or refresh AI search on an existing install:

cd ~/FileDepot
git pull
sudo scripts/enable-filedepot-ai-search.sh
sudo scripts/apply-filedepot-server-branding.sh

To opt out during install:

FILEDEPOT_ENABLE_AI_SEARCH=0

Provider Answers

To enable Claude answers, set provider values in /opt/filedepot/.env:

FILEDEPOT_AI_PROVIDER=anthropic
FILEDEPOT_AI_MODEL=claude-haiku-4-5-20251001
ANTHROPIC_API_KEY=your-key-here
FILEDEPOT_AI_REDACT_SECRETS=true
FILEDEPOT_AI_MAX_PROVIDER_PASSAGE_CHARS=1400
FILEDEPOT_AI_ANSWER_CACHE_TTL=604800
FILEDEPOT_AI_MAX_RAG_PASSAGES=12

External answer providers receive only bounded top-ranked passages, not whole files. When redaction is enabled, FileDepot masks likely passwords, API keys, tokens, private keys, bearer/basic auth values, and connection-string passwords before provider submission.

Administrators can also open System Admin and use the AI Providers panel to draft answer, embedding, vector, redaction, cache, and source-limit settings. The panel intentionally generates server .env lines instead of storing secrets in the browser; API keys should stay in /opt/filedepot/.env or a secret manager. Use Copy apply command from that panel on the FileDepot server to validate settings, update /opt/filedepot/.env, rebuild/restart AI search, and reapply branding.

The answer UI is designed to show:

• Short direct answer first.
• Optional More detail bullets.
• Clickable reference documents.
• Ranked passages below the answer.
• Copy controls for answers and individual results.
• Cache age when an answer is served from cache.

FileDepot can also show a separate General AI answer beside the FileDepot answer. General answers are labeled as general knowledge and do not receive private FileDepot passages. Disable them with:

FILEDEPOT_AI_GENERAL_ANSWER=false

Answer Cache

Generated answers are cached for seven days by default to reduce token usage. Cache keys include the signed-in session, query, provider/model, redaction setting, answer type, and selected source passages. Search results remain fresh while cached answers show their age in the UI.

Vector Retrieval Foundation

FileDepot now includes the first vector-backed retrieval foundation. The default embedding provider is local_hash, a local deterministic embedding path that stores passage vectors in the AI sidecar SQLite database. It does not call a cloud service and does not send file contents outside the server.

The local provider is intentionally conservative: keyword/BM25-style ranking still stays primary, while vector scores are blended in with a bounded weight. This creates the schema, provider interface, status reporting, and hybrid-scoring path needed for future Qdrant, pgvector, OpenSearch, cloud embedding, or on-prem embedding providers.

Relevant settings:

FILEDEPOT_AI_VECTOR_SEARCH=true
FILEDEPOT_AI_EMBEDDING_PROVIDER=local_hash
FILEDEPOT_AI_EMBEDDING_MODEL=local_hash
FILEDEPOT_AI_VECTOR_STORE_BACKEND=sqlite
FILEDEPOT_AI_VECTOR_DIMENSIONS=384
FILEDEPOT_AI_VECTOR_WEIGHT=0.25
FILEDEPOT_AI_VECTOR_MIN_SCORE=0.08

FILEDEPOT_AI_VECTOR_BACKEND=local_hash is still accepted as a legacy alias for the embedding provider. Use local_hash for the current privacy-safe foundation. Future embedding providers should remain selectable and policy-aware, especially for sources marked search-only or on-prem-only.

Compiled Knowledge

The compiled knowledge layer creates durable context artifacts from indexed passages. The current implementation is local and extractive, so it does not call Claude or send extra file content to an external provider.

Compiled artifacts currently include:

• File summaries, used as compact orientation for individual documents.
• Topic summaries, used to identify recurring concepts across the accessible index.
• Technical entity summaries, used to connect tools, platforms, formats, and systems such as PowerShell, Ubuntu, SMB, NTFS, Docker, and related admin terms.

Compiled knowledge is supporting context only. FileDepot answers still cite raw retrieved passages, not compiled summaries, topics, or entities.

Compiled knowledge is exposed through:

GET  /ai-search/compiled-knowledge
POST /ai-search/compiled-knowledge/compile

This layer prepares FileDepot for larger deployments where search should rely on a mix of exact matches, passages, summaries, future vectors, source policies, and permission-aware retrieval.

External Sources

Administrators can use the FileDepot External Sources panel in System Admin to draft read-only SMB, NTFS, or mounted-folder source definitions.

External source indexing is intentionally conservative. Mount the source on the Docker host first, copy the generated configuration into /opt/filedepot/.env, and expose only read-only paths to FileDepot.

Example:

FILEDEPOT_AI_EXTERNAL_SOURCES_JSON=[{"name":"Accounting Share","path":"/mnt/filedepot-sources/accounting","type":"smb","enabled":true,"read_only":true,"permission_mode":"admin","notes":"Mounted read-only on the FileDepot server"}]

Do not store passwords, access keys, or SMB credentials in this value. Use OS mount configuration or a secrets manager for credentials.

Project Architecture

The AI sidecar is split into focused modules:

services/ai-search/
├── app.py                  FastAPI endpoints
├── indexer.py              FileDepot crawling and passage indexing
├── search_engine.py        Ranking and retrieval
├── rag.py                  Grounded and general answers
├── provider_client.py      AI provider gateway
├── answer_cache.py         Seven-day answer cache
├── redaction.py            Secret masking
├── compiled_knowledge.py   Durable summaries and compiled artifacts
├── index_store.py          SQLite persistence
└── models.py               Shared data shapes

The long-term direction is a scalable hybrid search system:

raw files
  -> text extraction
  -> semantic chunks
  -> exact/keyword index
  -> vector index
  -> compiled knowledge
  -> permission-scoped retrieval
  -> cited answers and summaries

This roadmap is captured in the architecture decision records under docs/adr.

Repository Layout

app/                 command-line client entry points
daemon/              sync daemon and background services
common/              shared sync, storage, crypto, and utility code
lib/                 client library and RPC bindings
python/              Python client package
doc/                 man pages and CLI notes
debian/              Debian packaging files
deploy/              server deployment notes
dmg/                 macOS packaging assets
docs/                install, operations, and architecture docs
msi/                 Windows installer assets
scripts/             build, install, branding, and server helper scripts
services/ai-search/  AI search sidecar
tests/               tests and test helpers
integration-tests/   integration setup helpers

Compatibility Notes

FileDepot is a new project line built from a mature file-sync codebase. Some internal names still appear in command names, import paths, binary names, container names, data paths, and compatibility layers.

Examples include seaf-cli, seaf-daemon, libseafile, python/seafile, and seafile-data. These should be renamed only with migration planning, tests, and backwards-compatible data handling.

New user-facing work should use FileDepot language.

Linux Build

These steps target Ubuntu or Debian-style systems.

1. Install Build Dependencies

sudo apt update
sudo apt install -y \
  git build-essential autoconf automake libtool intltool pkg-config \
  python3 python3-dev valac \
  libglib2.0-dev libevent-dev libsqlite3-dev libcurl4-openssl-dev \
  libjansson-dev zlib1g-dev libssl-dev libargon2-dev libwebsockets-dev

2. Build And Install libsearpc

FileDepot currently depends on libsearpc.

mkdir -p ~/src
cd ~/src
git clone <your-approved-libsearpc-source-url> libsearpc
cd libsearpc

./autogen.sh
./configure --prefix=/usr/local --with-python3
make -j"$(nproc)"
sudo make install
sudo ldconfig

If pkg-config cannot find libsearpc, export the local pkg-config path:

export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"

3. Build FileDepot

cd ~/src
git clone https://github.com/cdburgess75/FileDepot.git
cd FileDepot

./autogen.sh
./configure --prefix=/usr/local --with-python3
make -j"$(nproc)"
make check
sudo make install
sudo ldconfig

Local Development

For an in-tree development build:

./autogen.sh
./configure --with-python3
make -j"$(nproc)"
make check

On systems where Vala is difficult to install, this repository includes build-tools/valac, a small local shim used for development builds that rely on checked-in generated C sources in lib/. A full release build should use a real Vala compiler when regenerating those sources.

Common Client Commands

Initialize a local client configuration:

seaf-cli init -d ~/filedepot-client

Start the daemon:

seaf-cli start

Stop the daemon:

seaf-cli stop

Show synchronized depots:

seaf-cli list

The command names currently remain seaf-cli and seaf-daemon for compatibility.

Project Direction

Near-term work focuses on:

• Clean FileDepot-first documentation and public project identity.
• Preserving working server installs while replacing legacy UI language.
• Stronger AI search retrieval through exact, keyword, compiled-knowledge, and future vector indexes.
• Admin-managed source and indexing policies.
• Safer provider controls, redaction defaults, and answer caching.
• Smoke tests that prove install, branding, AI health, and critical UI assumptions.
• Planned migration away from old internal names only when compatibility is protected.

License And Credits

See LICENSE.txt.

Open-source credits and the FileDepot ingredient log live in GUMBO.md.