localgo

README

LocalGo

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

Table of Contents

• Features
• Quick Start
• Configuration
• Commands
• Documentation
• Troubleshooting
• For Developers
• Contributing
• License

Features

• Complete LocalSend v2.1 Protocol - Works with LocalSend apps
• Secure - HTTPS with certificates, optional PIN protection
• Fast Discovery - Multicast UDP + HTTP fallback
• Multi-file Transfers - Send multiple files concurrently
• Web Share - Share files via browser download link
• Clipboard Integration - Incoming text/plain transfers copied to clipboard automatically
• Metadata Preserved - File timestamps preserved on transfer
• Cross-Platform - Linux, macOS, Windows

Quick Start

Installation

User installation (recommended)

# clone repo
git clone https://github.com/bethropolis/localgo.git
cd localgo

# installs a user systemd service and completions
./scripts/install.sh

using aur (Arch Linux)

yay -S localgo-bin

using homebrew (macOS/Linux)

brew tap bethropolis/tap
brew install localgo

using scoop (Windows)

scoop bucket add bethropolis https://github.com/bethropolis/scoop-bucket
scoop install localgo

[!NOTE] more install options in installation documentation

Usage

# Start server to receive files
localgo serve

# Discover devices
localgo discover

# Send a file
localgo send --file document.pdf --to "My Phone"

# Send clipboard contents directly
localgo send --clipboard --to "My Phone"

# Inspect transfer history logs
localgo history

# Share files for web download
localgo share --file document.pdf

[!TIP] To get the best visual experience with localgo's modern terminal interface, using a Nerd Font (e.g. JetBrainsMono, FiraCode) is highly recommended.

Docker and Podman

For full details — deployment, macvlan networking, read-only root filesystem, watchtower, and more — see the container documentation.

Configuration

Environment Variables

Variable	Default	Description
LOCALSEND_ALIAS	hostname	Device name
LOCALSEND_PORT	53317	Server port
LOCALSEND_DOWNLOAD_DIR	./downloads	Download directory
LOCALSEND_PIN	—	Optional PIN protection
LOCALSEND_FORCE_HTTP	false	Use HTTP instead of HTTPS
LOCALSEND_DEVICE_TYPE	desktop	Device type (mobile/desktop/laptop/tablet/server/headless/web/other)
LOCALSEND_DEVICE_MODEL	LocalGo	Device model string
LOCALSEND_AUTO_ACCEPT	false	Auto-accept incoming files without prompting
LOCALSEND_NO_CLIPBOARD	false	Save incoming text as a file instead of clipboard
LOCALSEND_LOG_LEVEL	info	Log verbosity (debug/info/warn/error)

Example

export LOCALSEND_ALIAS="File Server"
export LOCALSEND_DOWNLOAD_DIR="/srv/files"
export LOCALSEND_PIN="123456"
localgo serve

Commands

Command	Description
serve	Start server to receive files
share	Share files via web download
discover	Find devices via multicast
scan	Find devices via HTTP scan
send	Send files to a device
history	Show file transfer history log
info	Show device information
devices	List discovered devices

Run localgo help for more options.

Documentation

Detailed guides available in docs/:

• Configuration - All settings
• Container - Container deployment
• CLI Reference - Command details
• Deployment - Production setup

Troubleshooting

Discovery not working:

# Use HTTP scan instead
localgo scan --timeout 15

Port in use:

# Use different port
localgo serve --port 8080

Permission denied:

# Fix download directory
chmod 755 ~/Downloads/LocalGo

For Developers

Want to build on top of LocalGo or contribute?

• Library Guide: How to use LocalGo as a Go library.
• Code Walkthrough: Understand the internal architecture.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file.