High-performance, production-ready LocalSend protocol receiver built in Go. Receive files from any LocalSend-compatible device (iOS, Android, Windows, macOS, Linux) on your NAS or server seamlessly.

• 🔐 Native HTTPS — Auto-generates RSA-2048 self-signed TLS certificates at startup. No external reverse proxy needed.
• 📡 UDP Multicast Discovery — Automatically announces availability to the local network using LocalSend protocol v2.
• 📦 Seamless File Reception — Stream-based file reception with automatic duplicate renaming (file_timestamp.ext). Files are organized into {sender_fingerprint}/YYYY/MM/ subdirectories based on the sender device fingerprint and file's modified time metadata.
• 🛡️ Admin Dashboard — Modern responsive web UI at 0.0.0.0:53318 for monitoring transfers, managing files, and configuring settings. Mobile-friendly with responsive layout.
• ♻️ Resource Efficient — Capped log buffer (1000 entries), ~9MB static binary, ~10MB memory footprint.
• 🐳 Docker Ready — Multi-stage build with health checks, resource limits, and volume persistence.
• 🚀 Zero Dependencies — Single static binary with no runtime dependencies. Deploy anywhere.

# Build from source
go build -o localsend-hub . && go build -o localsend-hub-admin ./cmd/admin

# Run core service (file reception)
./localsend-hub

# Run admin service (management UI) - in another terminal
./localsend-hub-admin

# Build and run (starts both services)
./docker.sh
# or: docker compose up -d

# Access admin panel
open http://localhost:53318

docker compose up -d

This mounts ./data/received and ./data/config for persistent storage.

LocalSend Hub uses a dual-service decoupled architecture for fault isolation:

                   ┌───────────────────────────────────────────┐
                   │           Container / Host                │
                   │                                           │
  ┌────────────┐   │  ┌──────────────┐      ┌──────────────┐   │
  │ LocalSend  │   │  │ Core Service │      │ Admin Service│   │
  │ Clients    │◄──┤  │ Port 53317   │      │ Port 53318   │   │
  │ (Mobile)   │   │  │ (HTTPS)      │      │ (HTTP/Local) │   │
  └────────────┘   │  │              │      │              │   │
                   │  │ - TLS Gen    │      │ - Web UI     │   │
        ┌──────────┤  │ - File Save  │      │ - API        │   │
        │          │  │ - Multicast  │      │ - Config     │   │
        ▼          │  └──────────────┘      └──────────────┘   │
  Shared Config File            ┌──────────────────┐            │
  (localsend_config.json)       │ Shared SQLite DB │            │
  - Config  - Device Identity   │ (Transfer Logs)  │            │
                                └──────────────────┘            │
└───────────────────────────────────────────────────────────────┘

Key Benefits:

• Fault Isolation: If Admin Service crashes, Core Service continues receiving files
• Independent Scaling: Each service can be deployed/scaled separately
• Clean Separation: Clear boundaries between file reception and management concerns
• Consistent Logs: Both services share the same SQLite database, no stale data

.
├── main.go                     # Core service entry point
├── cmd/
│   └── admin/
│       └── main.go             # Admin service entry point
├── internal/                   # Private implementation (not importable)
│   ├── state/                  # 💾 Thread-safe config, sessions
│   │   ├── state.go            # Core service state management
│   │   ├── admin_state.go      # Admin service state management
│   │   ├── shared.go           # Shared types (LogEntry, ConfigData)
│   │   └── admin_provider.go   # Interface for cross-process state
│   │   └── persistence.go      # JSON config file I/O
│   ├── db/                     # 🗄️ SQLite database layer
│   │   └── logdb.go            # Transfer logs persistence
│   ├── discovery/              # 📡 UDP multicast announcer
│   │   └── multicast.go        # Periodic network discovery
│   ├── core/                   # 🌐 HTTPS server + LocalSend handlers
│   │   └── server.go           # TLS cert gen, API endpoints
│   └── admin/                  # 🛡️ Admin panel + embedded web UI
│       ├── server.go           # HTTP server with go:embed
│       └── web/                # Frontend assets
│           ├── index.html      # Dashboard HTML
│           ├── style.css       # Dark/light theme CSS
│           └── app.js          # Vanilla JS frontend
├── Dockerfile                  # Multi-stage Docker build (both binaries)
├── docker-compose.yml          # Docker Compose configuration
├── entrypoint.sh               # Docker entrypoint (starts both services)
├── go.mod                      # Module definition
└── received/                   # [Git-ignored] File storage directory

Implements the LocalSend Protocol v2.

LocalSend Hub uses a simple layered configuration:

1. Built-in defaults — loaded first
2. Config file — overrides defaults (if file exists)
3. Environment variables — overrides everything (if set at startup)

Settings changed via the Admin UI are automatically saved to the config file. Environment variables take effect at container startup and override config file values.

LocalSend Hub persists configuration to localsend_config.json. In Docker, the default path is /app/config/localsend_config.json (mounted via volume). The file is auto-created on first run and saved every 15 seconds or on config change.

Transfer logs are stored in a separate SQLite database (localsend_logs.db), ensuring real-time consistency between both services without file polling.

{
  "receiveDir": "./received",
  "corePort": 53317,
  "adminPort": 53318,
  "alias": "LocalSend Hub",
  "deviceModel": "LocalSend Hub Server",
  "deviceType": "server",
  "maxLogs": 1000
}

Pull the official image from GitHub Container Registry:

# Pull latest stable release
docker pull ghcr.io/linychuo/localsend-hub:latest

# Or pull a specific version
docker pull ghcr.io/linychuo/localsend-hub:v1.0.0

# Using official image from GHCR
docker run -d \
  --name localsend-hub \
  --network host \
  -v $(pwd)/data/received:/app/received \
  -v $(pwd)/data/config:/app/config \
  -v $(pwd)/data/sqlite:/app/data \
  ghcr.io/linychuo/localsend-hub:latest

Or using Docker Compose:

docker compose up -d

docker build -t localsend-hub .
docker run -d \
  --name localsend-hub \
  -p 53317:53317 \
  -p 53318:53318 \
  -v $(pwd)/data/received:/app/received \
  -v $(pwd)/data/config:/app/config \
  -v $(pwd)/data/sqlite:/app/data \
  localsend-hub

For multicast to work across your local network, use network_mode: host in Docker Compose:

services:
  localsend-hub:
    network_mode: host
    volumes:
      - ./data/received:/app/received
      - ./data/config:/app/config
      - ./data/sqlite:/app/data

⚠️ Note: network_mode: host removes network isolation. Only use on trusted networks.

The container includes an automatic health check that verifies the admin API is responsive every 30 seconds.

• Ensure UDP port 53317 is not blocked by firewall rules.
• If using Docker, verify multicast routing with network_mode: host.
• Some routers block multicast; check your network configuration.

• The admin panel binds to 0.0.0.0:53318 and is accessible from LAN.
• For secure remote access, use SSH tunneling: ssh -L 53318:localhost:53318 user@server
• Or add authentication (Basic Auth) before exposing to untrusted networks.

• Verify the received/ directory exists and has write permissions.
• Check logs via admin panel: http://localhost:53318

See requirements.md for detailed feature specifications.

• LocalSend Protocol Specification
• Architecture Design Document
• Feature Requirements

MIT License. See LICENSE for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

• LocalSend — For the open protocol specification
• Go standard library — For the robust net/http, crypto/tls, and net packages