DirForge

DirForge is a simple yet practical read-only directory browsing web application, designed specifically for home labs and advanced NAS users. It is a stateless, read-only web file browser with no database, no background worker processes, and no writing to disk—just point a mounted path at it and it is ready to use. This makes it very lightweight and easy to deploy.

Main Purpose

The core purpose of DirForge is to let users securely browse, search, and retrieve files in a specific directory on a server through a browser or API, without granting write permissions. It is suitable for scenarios that require quickly viewing files on a NAS or server, sharing a single file or an entire folder, and allowing AI assistants to access the file system.

Core Features

• Web Interface: List and grid views, support for sorting by name, size, and date, and light/dark themes.
• File Preview: Popup previews for text, images, videos, audio, and PDFs, with lightbox navigation for images.
• Archive Browsing: View the contents of .zip, .tar, .tar.gz, .tgz, and .gz files in the browser.
• Search: Recursive search with configurable depth and time budget.
• File Operations: Support direct download of individual files, or package an entire folder as a ZIP for download (configurable maximum size).
• Sharing: Generate signed share links with expiration, one-time share links, and QR codes for share links.
• Hashing and Verification: Calculate file hashes (CRC32, MD5, SHA-1, SHA-256, SHA-512), and support verification of .md5, .sha1, and other checksum files.
• Read-only WebDAV: Located at /webdav/, supports OPTIONS, PROPFIND, GET, and HEAD methods, compatible with Windows Explorer, macOS Finder, and others.
• S3-compatible API: Located at /s3/, supports operations such as ListBuckets, GetBucketLocation, ListObjectsV2, GetObject, and HeadObject, compatible with aws cli, rclone, and MinIO clients. Uses AWS Signature V4 authentication.
• MCP Server: Located at /mcp/, allows AI assistants (such as Claude Code, Codex)to browse directories, read files, search by name or content, check hashes, find duplicate files, get disk usage reports, and more.
• RESTful JSON API: Located at /api/, used for browsing, searching, sharing, and archiving.
• Dashboard and Metrics: In-memory dashboard located at /dashboard, with configurable separate credentials; Prometheus metrics located at /metrics; integrated statistics JSON located at /dashboard/stats.

Usage

Dependencies and Installation

Requires Docker or Podman (images support amd64 and arm64). Standalone versions can also be downloaded from the latest release: dirforge-win-x64.zip for Windows, dirforge-linux-x64.tar.gz or linux-arm64 for Linux.

Quick Start (Docker/Podman)

Run the container using Docker or Podman; see the official documentation for the specific commands and Compose examples. Podman 4.1+ can use the podman compose subcommand. On SELinux systems, mounted volumes need :z added, such as -v /srv/share:/data:ro,z.

Standalone Deployment (Windows)

1. Download and extract dirforge-win-x64.zip.
2. Edit appsettings.json and set RootPath to the directory to be shared.
3. Console mode: double-click DirForge.exe to run.
4. Windows service: run install-service.bat as administrator, and the service will start with the system; use uninstall-service.bat to uninstall.

Standalone Deployment (Linux)

1. Download and extract the tar package to /opt/dirforge.
2. Run ./DirForge directly, or install it as a systemd service (the tarball includes an example dirforge.service).

Access and Configuration

Default access http://localhost:8091。配置项可在 defined in src/DirForge/appsettings.json and overridden by environment variables of the same name. Boolean values must be true or false. See .env.example for the full set of options. It is recommended to mount only the directories that need to be exposed, and to prefer read-only mounts (:ro).

Security and Limitations

• Authentication: Supports HTTP Basic Auth, Bearer Token (via a configurable header), and reverse proxy external authentication (such as Authelia, Authentik). Basic and Bearer can be enabled at the same time; either one passing is sufficient.
• Security policies: Supports hiding files via dotfile flags or glob patterns, denying downloads by extension, and fixed-window rate limiting (per IP and global). Hidden paths and denied extensions apply to both direct downloads and ZIP output.
• WebDAV limitations: The Windows Explorer WebDAV client refuses Basic Auth over plain HTTP by default; HTTPS (recommended) is required, or the registry BasicAuthLevel must be set to 2. All write methods return 405.
• S3 limitations: Disabled by default; EnableS3Endpoint=true must be set. All write operations return 405. Credentials are required, otherwise the application cannot start.
• MCP limitations: Requires EnableMcpEndpoint=true (the default) and a configured BearerToken. All hiding/denial/authentication policies apply equally.
• Symbolic links and hard links: DirForge follows symbolic links, but enforces containment—every link target must resolve to a path under RootPath, otherwise it is silently blocked. Recursive operations track visited canonical paths to prevent loops. Hard links are treated as ordinary files with no special handling.
• Default credential warning: The default compose file falls back to admin/dirforge when BasicAuthUser and BasicAuthPass are not set; be sure to change these before exposing to a network.
• The baseline defaults are aimed at home networks and are not hardened for the internet. It is recommended to set ShareSecret to a long random value in production, otherwise share links are reset after a restart.
• Dashboard and metrics data are stored in memory only and are reset after a restart.
• Static UI assets are served from /dirforge-assets/* and are intentionally public.

Use Cases

DirForge is well suited for home lab users, NAS administrators, individuals who need to securely share files or folders, developers who want to give AI assistants access to the file system, and automation scenarios that need to integrate file browsing via the S3 or WebDAV protocols.

Category

Based on its characteristics as an AI development platform/MCP server, DirForge is classified as an AI development platform (ai-frameworks).