Foxel is a self-hosted private cloud storage platform designed for individuals and teams who need to centralize and intelligently search files across diverse storage systems. It solves the problem of fragmented data by providing a unified interface to manage files on local disks, S3, Google Drive, Dropbox, WebDAV, and more — all while enabling natural language search through AI embeddings. Built for privacy-conscious users, it avoids cloud vendor lock-in and offers full control over data.
Technically, Foxel combines a Python/FastAPI backend with a React 19/TypeScript frontend, using Tortoise ORM for data persistence and Milvus/Qdrant for vector embeddings. It supports Docker Compose deployment, JWT-based authentication, and a plugin system that allows runtime extension of both frontend and backend functionality without modifying core code.
What You Get
- Unified File Management - Browse, upload, download, move, copy, and delete files across multiple storage backends through a single interface, eliminating context switching between cloud services.
- Pluggable Storage Backends - Supports 10+ storage adapters including S3-compatible, WebDAV, SFTP, FTP, Google Drive, OneDrive, Dropbox, Quark, Telegram, AList, and Foxel-to-Foxel, all via an extensible adapter pattern.
- AI-Powered Semantic Search - Search images, PDFs, and documents using natural language queries (e.g., “find photos of dogs at the beach”) powered by configurable embedding models and vector databases like Milvus and Qdrant.
- Built-in File Preview - View images, videos, PDFs, Office documents, text, and code files directly in the browser without downloading, with support for thumbnails and inline rendering.
- Role-Based Access Control (RBAC) - Enforce granular permissions with built-in Admin/User/Viewer roles, custom roles, path-based rules using wildcards and regex, and fine-grained read/write/delete/share controls per folder.
- Background Task Processing - Run asynchronous jobs like file indexing, data backups, and scheduled tasks without blocking the main application, managed through a dedicated task center.
- AI Agent Integration - An embedded AI agent with tools for VFS operations, web fetching, and file processing to automate tasks like metadata extraction or content summarization.
- Protocol Mappings - Access files via S3 API, WebDAV (for OS mounting), and signed temporary URLs, enabling integration with existing tools and workflows.
- Public & Password-Protected Sharing - Generate shareable links with configurable expiration dates; recipients can browse shared content without needing an account.
Common Use Cases
- Personal photo and document archiving - A user organizes thousands of photos and PDFs from multiple devices and cloud services into one searchable private cloud, using semantic search to find images by description without tagging.
- Team collaboration with fine-grained permissions - A small design team shares Figma files, videos, and client documents via Foxel, assigning path-based access rules so only certain members can edit specific folders.
- Unified search across hybrid storage - A researcher aggregates data from local NAS, Google Drive, and S3 buckets and uses natural language queries to find relevant research papers or images without knowing exact filenames.
- Self-hosted alternative to Dropbox/OneDrive - A privacy-focused user replaces commercial cloud storage with Foxel, retaining full control over data while gaining AI search and WebDAV/S3 compatibility for existing tooling.
Under The Hood
Architecture
- Monolithic FastAPI backend with tightly coupled domain layers lacking clear interface segregation or dependency injection
- Service components instantiated directly, violating inversion of control principles
- MCP protocol exposed directly on main API surface without encapsulation
- SPAStaticFiles middleware manually handles frontend routing fallbacks, bypassing standard proxy patterns
- Plugin system dynamically loaded but lacks lifecycle management, interface contracts, or sandboxing
Tech Stack
- Python 3.14 backend using FastAPI, Pydantic, and Tortoise-ORM for async data operations
- Qdrant and Milvus Lite integrated for semantic search and vector embeddings
- Bun 1.2 with React and Ant Design for frontend build and UI components
- Dockerized deployment with multi-stage builds, Gunicorn, and environment-driven configuration
- External integrations via Telethon and Paramiko for Telegram and SSH-based file operations
Code Quality
- Extensive test suite with abundant functions but lacking meaningful assertions, reducing reliability
- UI and business logic poorly separated in React components, increasing coupling risk
- Generic error handling with minimal context impairs debugging and user feedback
- Inconsistent naming conventions across components and utilities, hindering readability
- Limited type safety due to absence of TypeScript, leading to runtime vulnerabilities
- Linting is inconsistently applied, allowing style drift and reducing maintainability
What Makes It Unique
- Integrated MCP as a dynamic API layer enables real-time extension of AI agent capabilities through plugins without rigid contracts
- Unified SPA architecture with intelligent routing fallback eliminates need for separate frontend servers or complex reverse proxies
- Extensible file processor system allows runtime registration of domain-specific file transformations
- Context-aware AI agent widget adapts to file path context to enable intelligent, input-free file operations
- Plugin-first design with runtime registry supports dynamic discovery and invocation of third-party tools without restarts