Foxel

Foxel is a self-hosted private cloud storage platform built for individuals and teams who want to centralize files across many storage backends and search them intelligently using AI. It unifies local disk, S3-compatible object storage, WebDAV, SFTP, FTP, Google Drive, OneDrive, Dropbox, Quark, Telegram, and AList through a single browser-based interface — eliminating the need to context-switch between a dozen different cloud apps.

What sets Foxel apart from typical file managers is its deep AI integration. It indexes content using configurable embedding models and stores vectors in Milvus Lite or Qdrant, letting you find images, PDFs, and documents with natural language queries rather than exact filename matches. The same embedding infrastructure powers an integrated AI agent that can perform VFS operations, fetch web content, and process files on your behalf directly from the interface.

Foxel also exposes its storage layer through standard protocols — an S3-compatible API, a WebDAV endpoint, and time-limited signed URLs — so existing tools like rclone, Cyberduck, and the AWS CLI continue to work without modification. A manifest-based plugin system allows runtime installation of .foxpkg bundles that extend both the Python API and the React frontend simultaneously, without requiring restarts or core code changes.

Deployment is straightforward via Docker Compose with a single container that bundles the Python backend, pre-built React frontend, and embedded vector database, making it an accessible choice for privacy-conscious users and teams who want full data sovereignty without infrastructure complexity.

What You Get

• Unified file management dashboard - Browse, upload, download, move, copy, rename, and delete files across 13+ storage backends through one interface, with support for both offset pagination and cursor-based pagination for large directories.
• AI semantic search - Index files using configurable embedding providers (OpenAI-compatible or local models) stored in Milvus Lite or Qdrant, then retrieve images, documents, and videos by natural language description rather than exact filename.
• Pluggable storage adapter system - Add support for local disk, S3, WebDAV, SFTP, FTP, Google Drive, OneDrive, Dropbox, Quark, Telegram, AList, or Foxel-to-Foxel through an auto-discovered adapter registry — new adapters load at startup with no core changes.
• Role-based access control with path rules - Define Admin, User, and Viewer system roles or create custom roles; enforce read/write/delete/share permissions per path with wildcard and regex pattern matching and priority-ordered rule evaluation.
• S3 API and WebDAV protocol access - Expose your unified storage through an S3-compatible endpoint and a WebDAV interface so existing tools like rclone, Cyberduck, and the AWS CLI connect without any custom integration work.
• Runtime plugin installation - Install .foxpkg bundles that register new Python API routes and inject React UI components into the running frontend simultaneously, without restarting the server or modifying core code.
• Integrated AI agent with MCP - An AI agent with built-in VFS tools is embedded in the interface, and the entire VFS surface is also exposed as an MCP server so external AI agents (Claude, Cursor, etc.) can operate on your files natively.
• Asynchronous task center - Run file indexing, data backups, and cron-scheduled jobs in a background worker queue that reports progress without blocking the main application.
• Shareable public links - Generate public or password-protected share links with configurable expiration times; recipients can browse shared folders and download files without an account.

Common Use Cases

• Personal photo and document archive - A user stores photos, scanned documents, and videos across a local NAS and a cloud drive, then uses Foxel’s semantic search to find images by description (e.g., ‘birthday party 2023’) without manual tagging.
• Team file collaboration with access control - A small team uses Foxel to share project assets, assigning path-based rules so designers can write to /design but only read /legal, enforced via custom roles.
• AI agent file operations - A developer connects an AI coding agent to Foxel’s MCP endpoint so the agent can read, write, and search project files across multiple storage backends as part of an automated workflow.
• Self-hosted Dropbox replacement - A privacy-focused user replaces Dropbox with Foxel, mounting it as a WebDAV network drive in their OS file manager while retaining AI search, sharing links, and Docker-based deployment.
• Hybrid storage aggregation - A researcher aggregates data from S3 buckets, a university SFTP server, and Google Drive into Foxel’s virtual file system, then queries across all sources with a single natural language search.
• Automated backup with scheduling - A sysadmin configures Foxel’s task center with cron expressions to run nightly backups between storage backends, with notifications sent on completion or failure.

Under The Hood

Architecture Foxel uses a monolithic FastAPI application with a deliberately layered domain structure. The VirtualFSService composes behavior from seven mixins — listing, file operations, transfer, processing, temp links, routing, and resolution — which achieves horizontal separation of concerns without deep inheritance. The storage adapter layer uses a Protocol-based interface discovered at startup via pkgutil module scanning, so new adapters are registered automatically when added to the providers package. The plugin system extends this pattern further: .foxpkg bundles are unpacked at runtime, their Python route modules are mounted onto the live FastAPI app, and their React bundles are served through a sandboxed iframe, all without a restart. The MCP server runs as a sub-application mounted at /api/mcp, giving AI agents structured tool access to VFS operations. The primary architectural trade-off is that services are consumed as class-method singletons — direct calls without dependency injection — which simplifies call sites but makes isolated testing difficult.

Tech Stack The backend runs Python 3.14 with FastAPI for async HTTP and WebSocket handling, Pydantic v2 for schema validation, Tortoise ORM for async database access against SQLite, and uv for fast, reproducible Python dependency resolution. The frontend is React 19 with TypeScript, built with Vite and Bun 1.2, using Ant Design 6 as the component library and React Router 7 for client-side navigation. Vector search is handled by either Milvus Lite (embedded, zero-config) or Qdrant (external, higher throughput), switchable via the settings UI. Storage protocol adapters leverage Telethon for Telegram, Paramiko for SFTP, and aioboto3 for S3-compatible stores. Docker multi-stage builds compile the frontend with Bun and package the Python backend into a single image deployed via Gunicorn with Uvicorn workers.

Code Quality No automated tests were found in the repository — no pytest files, no test directories — which is a significant gap for a project of this complexity. Error handling at the application boundary is well-structured: typed FastAPI exception handlers cover HTTP errors, validation failures, upstream HTTP errors, and unhandled exceptions, each returning consistent JSON. However, internal registry modules suppress errors with bare except Exception: continue patterns, meaning adapter or processor load failures are silently swallowed. The frontend uses TypeScript with ESLint (typescript-eslint and react-hooks plugins) configured, providing a reasonable quality baseline for the UI layer. Python service methods lack type annotations on many internal paths. Inline comments are present throughout but mix English and Chinese, which may create contribution friction for non-Chinese developers. No GitHub Actions CI configuration was found in the repository.

What Makes It Unique The most distinctive aspect of Foxel is its bidirectional MCP integration: the VFS is exposed as a native MCP server, making the entire storage layer directly consumable by AI agent frameworks without any custom API adapter. Paired with an embedded AI agent in the UI that is already context-aware of the current directory path, Foxel is arguably the first self-hosted file manager designed from the ground up to be an AI-native storage backend. The .foxpkg runtime plugin system is also genuinely unusual — injecting both backend routes and sandboxed frontend components into a live instance without restarts is a capability absent from comparable self-hosted solutions like Nextcloud or Immich. The combination of protocol emulation (S3 API + WebDAV) with semantic vector search and a plugin marketplace in a single Docker Compose deployment creates a surface area that no comparable open-source project currently covers.

Self-Hosting

Foxel is released under the MIT License, one of the most permissive open-source licenses available. You can use it commercially, modify it, redistribute it, and incorporate it into proprietary products without any copyleft obligations. The only requirement is preserving the copyright notice. There are no open-core restrictions, no feature flags gating capabilities behind a paid tier, and no license checks embedded in the codebase — everything in the repository is fully available to self-hosters.

Running Foxel yourself is straightforward at small scale but requires planning as usage grows. The recommended deployment is a single Docker Compose container that bundles the Python backend, React frontend, and SQLite database — adequate for personal use or small teams. For larger deployments, you will need to manage your own database persistence (SQLite has concurrency limits under heavy load), configure external vector database instances (Milvus Server or Qdrant rather than Milvus Lite), and handle storage backend credentials securely through environment variables. Foxel’s asynchronous task system and background workers add operational surface area that needs monitoring. Updates require pulling a new Docker image and restarting the container; there is no built-in rolling update mechanism. You are responsible for backups, uptime, TLS termination, and reverse proxy configuration.

There is no official managed or SaaS version of Foxel, so there is no hosted alternative to compare against. Support is community-driven through GitHub Issues and a Telegram group. The project does not offer SLAs, enterprise support contracts, managed backups, or high-availability configurations out of the box. For teams that need guaranteed uptime or compliance-grade audit trails beyond what the built-in audit logging provides, the operational burden falls entirely on the self-hoster to engineer. That said, for developers and technically proficient teams comfortable with Docker, Foxel offers a compelling degree of capability per unit of operational effort.