Filestash

Filestash is a self‑hosted, web‑based file manager that unifies access to heterogeneous storage backends—ranging from legacy protocols such as FTP/FTPS/SFTP/WebDAV to modern cloud services like S3, Minio, Google Drive, Dropbox, and even distributed block stores such as Storj. From a developer’s perspective, it presents itself as a modular, plugin‑driven platform that exposes a clean REST/GraphQL API (the MCP layer) and a flexible configuration model. The core application is written in Node.js with a lightweight Express‑style server, while the frontend leverages React and TypeScript, allowing developers to contribute UI components or replace entire themes without touching the backend logic.

Architecture

• Backend – Node.js (v18+), using a combination of native modules and node-fetch for HTTP integrations. Persistent state is minimal; user credentials, plugin metadata, and session tokens are stored in a lightweight SQLite database or can be swapped for any SQL engine via environment variables. The server exposes two primary interfaces: the API (RESTful endpoints for file operations, authentication, and plugin hooks) and the MCP (Machine‑to‑Machine API enabling LLM or CI/CD pipelines to manipulate files programmatically).
• Frontend – A single‑page application built with React, bundled by Vite. The UI is themeable through a dedicated plugin system; themes are simply React component trees that override default styles.
• Plugins – Implemented as NPM packages or local directories, each plugin follows a strict manifest (package.json) that declares its entry point, required APIs, and optional UI overrides. This architecture allows developers to ship new storage adapters (e.g., a custom S3‑compatible API) or UI widgets without modifying the core repository.

Core Capabilities

Deployment & Infrastructure

Filestash ships as a pre‑built Docker image (machines/filestash) that can be run on any platform supporting Docker or Podman. The image is built from a minimal Alpine base, keeping the footprint under 200 MB. For high‑availability setups, developers can run multiple instances behind a reverse proxy (NGINX/Traefik) with sticky sessions. The SQLite backend can be replaced by PostgreSQL or MySQL for multi‑tenant deployments, and the application supports environment‑based configuration (e.g., FS_STORAGE_BACKEND, FS_AUTH_METHOD). Horizontal scaling is straightforward: stateless API servers can be replicated, while the SQLite file must be shared via a network filesystem or migrated to a relational DB.

Integration & Extensibility

The plugin system is the linchpin of Filestash’s extensibility. Developers can write a simple Node module that implements the IStorageAdapter interface and publish it to npm or host it locally. The platform also offers webhooks for file events, allowing external services (e.g., CI pipelines or monitoring tools) to react to uploads/deletions. The MCP layer exposes LLM‑friendly endpoints, enabling integrations with chatbots or automated agents that can query or modify the file system. Custom authentication backends (OAuth2, LDAP, JWT) are supported through a pluggable auth provider API.

Developer Experience

Filestash’s documentation is comprehensive, with a dedicated “Getting Started” guide, API reference, and plugin inventory. The community is active on IRC (#filestash) and GitHub discussions; contributors are welcomed to submit PRs for new adapters or themes. Configuration is declarative, using environment variables and JSON files; no complex YAML or proprietary DSLs are required. The codebase follows standard JavaScript/TypeScript conventions, making it approachable for developers familiar with modern web stacks.

Use Cases

1. Enterprise File Gateway – Expose internal file shares (SFTP, SMB) to remote developers via a single web portal, eliminating the need for VPNs.
2. CI/CD Artifact Store – Use the MCP API to programmatically upload build artifacts to a shared S3 bucket or Git repository.
3. Personal Cloud – Combine Google Drive, Dropbox, and a local NAS behind one unified interface for home media consumption.
4. Data Lake Explorer – Mount a large Minio or Storj bucket, then use the built‑in viewer and transcoder for quick data inspection.

Advantages

• Performance – The lightweight Node backend and efficient caching of file metadata keep latency low, even over slow protocols.
• Flexibility – The adapter‑based architecture means any storage backend can be added with minimal