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

Fork the repository
Create a feature branch
Make your changes
Run tests: make test
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

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.github/workflows		.github/workflows
cmd/localgo-cli		cmd/localgo-cli
docs		docs
pkg		pkg
protocol		protocol
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

License

bethropolis/localgo

Folders and files

Latest commit

History

Repository files navigation

LocalGo

🚀 Features

Core Functionality

📦 Quick Start

Installation

Uninstallation

Basic Usage

Starting the Server

Sending Files

Discovery and Scanning

Device Information

⚙️ Configuration

Environment Variables

Configuration File

Command-Line Flags

🔧 System Service

Installation

Service Management

Service Configuration

🤖 Automation & Scripting

JSON Output

Batch Operations

Docker Integration

Quick Start

Manual Build

💻 Development

Building

Project Structure

Contributing

🌟 Examples

Home Media Server

Development Setup

Network Monitoring

🛠️ Troubleshooting

Common Issues

Debug Mode

📋 Protocol Compliance

📜 License

🙏 Acknowledgments

🔗 Related Projects

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Languages

Packages