IronDrop is a file server written in Rust. It serves directories, supports optional uploads, provides search, and includes a monitoring page. It ships as a single binary with embedded templates.
IronDrop focuses on predictable behavior, simplicity, and low overhead. Use it to serve or share files locally or on your network.
- File browsing and downloads with range requests and MIME detection
- Optional uploads with a drag-and-drop web UI (direct-to-disk streaming)
- Search (standard and ultra-compact modes for large directories)
- Monitoring dashboard at
/monitorand a JSON endpoint (/monitor?json=1) - Basic security features: rate limiting, optional Basic Auth, path safety checks
- Single binary; templates and assets are embedded
- Pure standard library networking and file I/O (no external HTTP stack or async runtime)
- Ultra-compact search index option for very large directory trees (tested up to ~10M entries)
Designed to keep memory usage steady and to stream large files without buffering them in memory. The ultra-compact search mode reduces memory for very large directory trees.
- Ultra-compact search: approximately ~110 MB of RAM for around 10 million paths; search latency depends on CPU, disk, and query specifics.
- No-dependency footprint: networking and file streaming are implemented with Rust's
std::netandstd::fs, producing a single self-contained binary.
Includes rate limiting, optional Basic Auth, basic input validation, and path traversal protection. See RFC & OWASP Compliance and Security Fixes for details.
Getting started with IronDrop is simple.
# Clone the repository
git clone https://github.com/dev-harsh1998/IronDrop.git
cd IronDrop
# Build the release binary
cargo build --release
# The executable will be in ./target/release/irondropTo use IronDrop from anywhere on your system, install it to a directory in your PATH:
# Linux/macOS - Install to /usr/local/bin (requires sudo)
sudo cp ./target/release/irondrop /usr/local/bin/
# Alternative: Install to ~/.local/bin (no sudo required)
mkdir -p ~/.local/bin
cp ./target/release/irondrop ~/.local/bin/
# Add ~/.local/bin to PATH if not already:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc
source ~/.bashrc # or restart terminal
# Windows (PowerShell as Administrator)
# Create program directory
New-Item -ItemType Directory -Force -Path "C:\Program Files\IronDrop"
# Copy executable
Copy-Item ".\target\release\irondrop.exe" "C:\Program Files\IronDrop\"
# Add to system PATH (requires restart or new terminal)
$env:PATH += ";C:\Program Files\IronDrop"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, [EnvironmentVariableTarget]::Machine)Verify Installation:
# Test that irondrop is available globally
irondrop --version
# Now you can run from any directory:
irondrop -d ~/Documents --listen 0.0.0.0Step 1: Download or build IronDrop
# Build from source (requires Rust)
git clone https://github.com/dev-harsh1998/IronDrop.git
cd IronDrop
cargo build --releaseStep 2: Start sharing files immediately
# Share your current directory (safest - local access only)
./target/release/irondrop -d .
# Share with your network (accessible to other devices)
./target/release/irondrop -d . --listen 0.0.0.0Step 3: Open your browser and visit http://localhost:8080
# Share your Downloads folder with family devices
irondrop -d ~/Downloads --listen 0.0.0.0 --port 8080# Secure file server with uploads and authentication
irondrop -d ./shared-files \
--enable-upload \
--username admin \
--password your-secure-password \
--listen 0.0.0.0# Serve your media collection (videos, music, photos)
irondrop -d /path/to/media \
--allowed-extensions "*.mp4,*.mp3,*.jpg,*.png" \
--threads 16 \
--listen 0.0.0.0# Use a configuration file for consistent setup
irondrop --config-file ./config/production.iniIronDrop offers extensive customization through command-line arguments:
| Option | Description | Example |
|---|---|---|
-d, --directory |
Required - Directory to serve | -d /home/user/files |
-l, --listen |
Listen address (default: 127.0.0.1) | -l 0.0.0.0 |
-p, --port |
Port number (default: 8080) | -p 3000 |
--enable-upload |
Enable file uploads | --enable-upload true |
--username/--password |
Basic authentication | --username admin --password secret |
-a, --allowed-extensions |
Restrict file types | -a "*.pdf,*.doc,*.zip" |
-t, --threads |
Worker threads (default: 8) | -t 16 |
--config-file |
Use INI configuration file | --config-file prod.ini |
-v, --verbose |
Debug logging | -v true |
For consistent deployments, use an INI configuration file:
# Create your config file
cp config/irondrop.ini my-server.ini
# Edit it with your settings
# Then run:
irondrop --config-file my-server.iniThe configuration file supports all command-line options and more! See the detailed example with comments explaining every option.
Configuration Priority (highest to lowest):
- Command line arguments
- Environment variables (
IRONDROP_*) - Configuration file
- Built-in defaults
Once IronDrop is running, these endpoints are available:
| Endpoint | Purpose | Example |
|---|---|---|
/ |
📁 Directory listing and file browsing | http://localhost:8080/ |
/monitor |
📊 Real-time server monitoring dashboard | http://localhost:8080/monitor |
/search?q=term |
🔍 File search API | http://localhost:8080/search?q=document |
/_irondrop/upload |
⬆️ File upload endpoint (if enabled) | Used by the web interface |
- Use authentication (
--username/--password) when exposing to untrusted networks - Adjust
--threadsbased on workload
# Get detailed help for all options
irondrop --help
# Check your version
irondrop --version
# Test with verbose logging
irondrop -d . --verbose trueFor comprehensive documentation, see our Complete Documentation Index.
Recent releases include direct-to-disk uploads, an ultra-compact search mode, and a /monitor page with a JSON endpoint.
IronDrop has extensive documentation covering its architecture, API, and features.
- Complete Documentation Index - Central hub for all documentation
- Architecture Guide - System design and component overview
- API Reference - Complete HTTP API documentation
- Deployment Guide - Production deployment strategies
- Search Feature Deep Dive - Ultra-compact search system details
- Upload Integration Guide - File upload system and UI
- Direct Upload System - Memory-efficient direct streaming architecture
- Configuration System - INI-based configuration guide
- Template System - Embedded template engine
- Security Fixes - Security enhancements and mitigations
- RFC & OWASP Compliance - Standards compliance details
- Testing Documentation - Comprehensive test suite overview
- Monitoring Guide - Real-time monitoring and metrics
IronDrop is rigorously tested with 106 comprehensive tests across 15 test files covering all aspects of functionality.
- Integration Tests (8 tests): End-to-end functionality and HTTP handling
- Monitor Tests (2 tests): Real-time monitoring dashboard and metrics
- Rate Limiter Tests (5 tests): Memory-based rate limiting and DoS protection
- Template Tests (7 tests): Embedded template system and rendering
- Ultra-Compact Search Tests (5 tests): Advanced search engine functionality
- Configuration Tests (12 tests): INI parsing and configuration validation
- Core Server & Unit Tests (41 tests): Library functions, utilities, and core logic
# Run all tests
cargo test
# Run specific test categories
cargo test comprehensive_test # Core server functionality
cargo test upload_integration # Upload system tests
cargo test edge_case_test # Edge cases and error handling
cargo test direct_upload_test # Direct streaming validation
# Run tests with output
cargo test -- --nocaptureFor detailed testing information, see Testing Documentation.
IronDrop is licensed under the MIT License.
Made with ❤️ and 🦀 in Rust
Zero dependencies • Production ready • Battle tested with 106 comprehensive tests
⭐ Star us on GitHub • Report an Issue • 📚 Read the Docs • 🧪 View Tests