HAMAL

Point-to-point local file transfer. The carrier for your digital cargo.

What is HAMAL?

HAMAL (Turkish for porter / carrier) is a fast, lightweight, self-hosted web application designed for frictionless, temporary file transfers across your local network (LAN / Wi-Fi).

In traditional culture, a hamal carries goods and heavy loads from one place to another. In HAMAL, the cargo is digital: files move directly between devices on your local network without intermediate cloud storage, permanent user accounts, advertising, or telemetry.

+---------------+                    +----------------+                    +-----------------+
|               |  1. Scans QR Code  |                |  2. Streams File   |                 |
|  Room Creator | -----------------> |  HAMAL Server  | <----------------- |   Participant   |
|   (Desktop)   |                    | (Local Network)|                    | (Mobile/Laptop) |
+---------------+                    +----------------+                    +-----------------+

Screenshots

Key Features

• 🚀 Zero Setup for Participants: Scan a QR code or open a local link to immediately upload or download files.
• ⏱️ Auto-Expiring Rooms: Rooms automatically expire and clean up files after a configurable TTL (5 minutes to 24 hours).
• 🔒 PIN Protection: Optional 4–8 digit PIN with exponential backoff and lockout to prevent brute-force attacks.
• 📦 True Streaming I/O: Multi-gigabyte transfers stream directly to disk without exhausting server RAM.
• 🎨 Warm Courier Aesthetics: Clean, modern interface in dark and light modes with warm amber courier accents.
• 🔍 Interactive QR Lightbox: One-click smooth zoom for scanning QR codes from across the room.
• 🛡️ Self-Hosted & Private: Zero cloud dependencies, zero external analytics, zero tracking.

Quick Start

Using Docker Compose (Recommended)

1. Clone the repository:

   git clone https://github.com/i1k3r/HAMAL.git
   cd HAMAL
   

2. Copy the sample environment file:

   cp compose.example.env .env
   

3. Start the container:

   docker compose up -d
   

4. Open your browser and navigate to:

   http://localhost:7700
   

Unraid Installation

1. Place unraid-template.xml into /boot/config/plugins/dockerMan/templates-user/ on your Unraid flash drive.
2. Go to the Docker tab in Unraid and click Add Container.
3. Select HAMAL from the template list.
4. Set your preferred web UI port and appdata directory path (/mnt/user/appdata/hamal), then click Apply.

Manual Binary Build (Go)

Prerequisites: Go 1.22+, GCC / CGO (for SQLite support).

# Clone the repository
git clone https://github.com/i1k3r/HAMAL.git
cd HAMAL

# Run tests
go test ./...

# Build the executable
go build -o hamal ./cmd/lan-drop

# Run HAMAL
./hamal

Configuration

HAMAL is configured via environment variables:

Brand Assets

Official HAMAL vector logos and icons are available in the brand/ directory:

• brand/hamal-logo-dark.svg (Horizontal dark-mode wordmark)
• brand/hamal-logo-light.svg (Horizontal light-mode wordmark)
• brand/hamal-logo-stacked.svg (Stacked badge wordmark)
• brand/hamal-app-icon.svg (Square container icon)
• brand/hamal-monochrome.svg (Monochrome asset)
• brand/hamal-path-mark.svg (Vector path symbol)

License

Released under the MIT License.