localgo

README

LocalGo

A Go implementation of the LocalSend protocol for secure, cross-platform file sharing.

🚀 Features

Core Functionality

• ✅ Complete LocalSend v2.1 Protocol - Full compatibility with LocalSend ecosystem
• ✅ Secure File Transfer - HTTPS with self-signed certificates and PIN protection
• ✅ Bidirectional Discovery - Multicast UDP + HTTP fallback for reliable device detection
• ✅ Smart Network Scanning - Automatically scans full subnet (/24) to find devices that block multicast
• ✅ Cross-Platform - Works on Linux, macOS, and Windows
• ✅ High Performance - Efficient file transfer with metadata (timestamps) preservation
• ✅ Zero Config - Works out of the box with auto-discovery

📦 Quick Start

Installation

Option 1: Automatic installation (Recommended)

# Default user installation (no sudo required)
./scripts/install.sh

# User installation with systemd service (auto-starts on login)
./scripts/install.sh --mode user --service

# System-wide installation (requires sudo)
sudo ./scripts/install.sh --mode system --service --create-user

Uninstallation

To remove LocalGo, run the uninstall script:

# Uninstall (will ask for confirmation)
./scripts/uninstall.sh

# Remove everything (config, data, user, etc.)
./scripts/uninstall.sh --remove-config --remove-data

Option 2: Manual build

git clone https://github.com/bethropolis/localgo.git
cd localgo
make build

Option 3: Go global install

go install github.com/bethropolis/localgo/cmd/localgo-cli@latest

Basic Usage

# Start server to receive files
localgo-cli serve

# Discover devices on network
localgo-cli discover

# Send a file
localgo-cli send --file document.pdf --to "John's Phone"

# Get help
localgo-cli help
localgo-cli help send

Starting the Server

# Basic server (HTTPS on port 53317)
localgo-cli serve

# Custom configuration
localgo-cli serve --port 8080 --http --alias "MyServer" --pin 123456

# With environment variables
export LOCALSEND_ALIAS="File Server"
export LOCALSEND_DOWNLOAD_DIR="/srv/files"
localgo-cli serve

Sending Files

# Send to specific device
localgo-cli send --file presentation.pptx --to "MacBook Pro"

# Send with custom timeout
localgo-cli send --file large-video.mp4 --to "Desktop" --timeout 300

# Send with custom sender alias
localgo-cli send --file report.pdf --to "Office PC" --alias "Mobile Device"

Discovery and Scanning

# Discover devices (multicast)
localgo-cli discover --timeout 10

# Scan network (HTTP)
localgo-cli scan --port 53317

# JSON output for scripting
localgo-cli discover --json | jq '.devices[].alias'

# Quiet mode for automation
localgo-cli scan --quiet --timeout 5

Device Information

# Show device configuration
localgo-cli info

# JSON format for scripts
localgo-cli info --json

# Check version
localgo-cli version

⚙️ Configuration

Environment Variables

# Device Configuration
LOCALSEND_ALIAS="My Device"              # Device name
LOCALSEND_PORT=53317                     # Server port
LOCALSEND_DOWNLOAD_DIR="./downloads"     # Download directory
LOCALSEND_DEVICE_TYPE="desktop"          # Device type

# Network Configuration
LOCALSEND_MULTICAST_GROUP="224.0.0.167" # Multicast address
LOCALSEND_FORCE_HTTP=false               # Use HTTP instead of HTTPS

# Security Configuration
LOCALSEND_PIN="123456"                   # PIN for authentication
LOCALSEND_SECURITY_DIR="./.localgo_security" # Security files location

# Logging Configuration
LOCALSEND_LOG_LEVEL="info"               # Log level (debug,info,warn,error)
LOCALSEND_VERBOSE=false                  # Verbose output
LOCALSEND_NO_COLOR=false                 # Disable colored output

Configuration File

Create localgo.env:

# Copy example configuration
cp scripts/localgo.env.example localgo.env

# Edit configuration
editor localgo.env

# Use configuration
source localgo.env && localgo-cli serve

For detailed configuration options, see docs/CONFIGURATION.md including:

• All environment variables
• Security directory paths (XDG-compliant)
• Command-line flags reference
• Migration from legacy paths

Command-Line Flags

Each command supports specific flags:

# Serve command
localgo-cli serve --port 8080 --http --pin 123456 --alias "Server" --dir "/tmp" --verbose

# Send command
localgo-cli send --file data.zip --to "Device" --port 8080 --timeout 60 --alias "Sender"

# Discovery commands
localgo-cli discover --timeout 10 --json --quiet
localgo-cli scan --port 8080 --timeout 15 --json

🔧 System Service

Installation

# Install as system service
sudo ./scripts/install.sh --mode system --service --create-user

Service Management

User Service:

# Enable and start
systemctl --user enable localgo
systemctl --user start localgo

# check status
systemctl --user status localgo

# View logs
journalctl --user -u localgo -f

System Service:

# Enable and start
sudo systemctl enable localgo
sudo systemctl start localgo

# Check status
sudo systemctl status localgo

# View logs
sudo journalctl -u localgo -f

Service Configuration

Edit /etc/localgo/localgo.env:

LOCALSEND_ALIAS="File Server"
LOCALSEND_PORT=53317
LOCALSEND_DOWNLOAD_DIR="/srv/localgo/downloads"
LOCALSEND_PIN="secure123"
LOCALSEND_DEVICE_TYPE="server"

🤖 Automation & Scripting

JSON Output

Perfect for integration with other tools:

# Get device list
DEVICES=$(localgo-cli scan --json --timeout 5)
echo "$DEVICES" | jq -r '.devices[].alias'

# Check if service is running
localgo-cli info --json | jq -r '.alias + " on port " + (.port|tostring)'

# Monitor file transfers
localgo-cli info --json | jq '.downloadDir'

Batch Operations

# Send multiple files
find /uploads -name "*.pdf" | while read file; do
    localgo-cli send --file "$file" --to "PrintServer"
done

# Health check script
#!/bin/bash
if localgo-cli info --json >/dev/null 2>&1; then
    echo "LocalGo is healthy"
    exit 0
else
    echo "LocalGo is not responding"
    exit 1
fi

Docker Integration

LocalGo includes full Docker support with docker-compose orchestration and volume persistence.

Quick Start

# Start with docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Manual Build

docker build -t localgo:latest .
docker run -d --name localgo --network host localgo:latest

For detailed Docker documentation, see docs/DOCKER.md including:

• Volume persistence and configuration
• Environment variables
• Network configuration (Linux/macOS/Windows)
• Health checks and troubleshooting
• Production deployment tips

💻 Development

Building

# Build binary
make build

# Run tests
make test

# Run with coverage
make test-coverage

# Clean build artifacts
make clean

Project Structure

localgo/
├── cmd/localgo-cli/           # CLI application entry point
├── pkg/                       # Core library packages
│   ├── cli/                  # CLI output utilities
│   ├── config/               # Configuration management
│   ├── crypto/               # TLS certificates and fingerprints
│   ├── discovery/            # Network discovery (multicast + HTTP)
│   ├── httputil/             # HTTP response utilities
│   ├── logging/              # Structured logging
│   ├── model/                # Data structures (Device, File, DTOs)
│   ├── network/              # Network interface utilities
│   ├── send/                 # File sending logic
│   ├── server/               # HTTP server and handlers
│   └── storage/              # File storage management
├── scripts/                  # Installation and utility scripts
├── protocol/                 # LocalSend protocol specification
└── downloads/                # Default download directory

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: make test
5. Submit a pull request

🌟 Examples

Home Media Server

# Configure as media server
export LOCALSEND_ALIAS="Home Media Server"
export LOCALSEND_DOWNLOAD_DIR="/media/shared"
export LOCALSEND_DEVICE_TYPE="server"
export LOCALSEND_PIN="family123"

# Install as system service
sudo ./scripts/install.sh --mode system --service --create-user

# Start service
sudo systemctl start localgo

Development Setup

# Configure for development
export LOCALSEND_ALIAS="Dev-$(whoami)"
export LOCALSEND_PORT=8080
export LOCALSEND_FORCE_HTTP=true
export LOCALSEND_VERBOSE=true
export LOCALSEND_LOG_LEVEL="debug"

# Start with verbose logging
localgo-cli serve --verbose

Network Monitoring

#!/bin/bash
# Monitor LocalGo devices on network

while true; do
    echo "=== LocalGo Network Scan $(date) ==="
    localgo-cli scan --json --timeout 10 | jq -r '
        .devices[] |
        "\(.alias) (\(.deviceType)) - \(.ip):\(.port) - \(.protocol)"
    '
    echo
    sleep 60
done

🛠️ Troubleshooting

Common Issues

Port already in use:

# Check what's using the port
sudo netstat -tlnp | grep 53317

# Use different port
localgo-cli serve --port 8080

Discovery not working:

# Check firewall
sudo ufw status

# Test network connectivity
localgo-cli scan --timeout 10

# Use HTTP discovery
localgo-cli scan --json

Permission denied:

# Fix download directory permissions
sudo chown -R $USER:$USER ~/Downloads/LocalGo

# Check service user permissions (systemd)
sudo journalctl -u localgo -n 50

Debug Mode

# Enable verbose logging
localgo-cli serve --verbose

# Debug network issues
export LOCALSEND_LOG_LEVEL="debug"
localgo-cli discover

📋 Protocol Compliance

LocalGo implements the complete LocalSend v2.1 protocol:

• ✅ Discovery API - /api/localsend/v2/register, /api/localsend/v2/info
• ✅ Upload API - /api/localsend/v2/prepare-upload, /api/localsend/v2/upload
• ✅ Download API - /api/localsend/v2/prepare-download, /api/localsend/v2/download
• ✅ Session Management - Proper session handling with tokens and timeouts
• ✅ Security - TLS encryption, fingerprint validation, PIN protection
• ✅ Discovery - Multicast UDP announcements with HTTP fallback

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• LocalSend Project - For the excellent protocol specification
• LocalSend Protocol - For detailed protocol documentation

🔗 Related Projects

• LocalSend - Original Flutter implementation
• LocalSend_rs - A cli Rust implementation

[!NOTE] This project was developed with the assistance of AI tools to enhance code quality and documentation.

---

thank you