LocalGo

A Go implementation of the LocalSend v2.2 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.2 Protocol - Works with LocalSend apps (v3 planned)
• Secure - HTTPS with auto-generated certificates, PIN-protected transfers, fingerprint TOFU verification
• Fast Discovery - Multicast UDP + HTTP fallback + CIDR range scanning
• Multi-file Transfers - Send multiple files concurrently with progress bars
• Web Share - Share files via browser download link with QR code and one-shot mode
• Clipboard Integration - Incoming text/plain transfers copied to clipboard instantly; send clipboard text directly
• Privacy Mode - Anonymize device identity during discovery and transfer (--private)
• Metadata Preserved - File timestamps preserved on transfer; EXIF/metadata stripping in private mode
• Cross-Platform - Linux, macOS, Windows, and Android (Termux)

Quick Start

Installation

Quick install (macOS, Linux, Termux)

curl -fsSL https://bethropolis.github.io/localgo/install.sh | bash

User installation

# 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

using mise (any platform)

mise use -g github:bethropolis/localgo

using docker / podman

mkdir -p localgo/downloads localgo/config
docker pull ghcr.io/bethropolis/localgo:latest
docker run -d \
  -p 53317:53317 \
  -v ./localgo/config:/app/config \
  -v ./localgo/downloads:/app/downloads \
  ghcr.io/bethropolis/localgo:latest

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"

# Send with PIN authentication
localgo send --file secret.pdf --to "My Phone" --pin 1234

# Fast discovery (skip cache probe)
localgo send --file large.zip --quick

# Send directly to an IP (skips discovery)
localgo send --ip 192.168.1.42:53317 --file photo.jpg

# Scan a specific CIDR range
localgo scan --range 192.168.1.0/24

# Inspect transfer history logs
localgo history

# Share files for web download (single-use)
localgo share --file document.pdf --once

# 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 on 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)
LOCALSEND_HISTORY	(auto)	Path to transfer history file
LOCALSEND_EXEC	—	Shell command to run after each received file
LOCALSEND_QUIET	false	Minimal output mode
LOCALSEND_CONCURRENCY	4	Max parallel upload workers
LOCALSEND_MULTICAST_INTERFACE	(all)	Network interface for multicast
LOCALSEND_MULTICAST_GROUP	224.0.0.167	Multicast group address
LOCALSEND_DISCOVERY_STRATEGY	full	Discovery strategy (full/fast)
LOCALSEND_SHELL	(auto)	Shell prefix for exec hooks
LOCALSEND_CLIPBOARD_WRITE_CMD	(auto)	Custom clipboard write command
LOCALSEND_CLIPBOARD_READ_CMD	(auto)	Custom clipboard read command
LOCALSEND_TLS_CERT	—	Custom TLS certificate path
LOCALSEND_TLS_KEY	—	Custom TLS private key path
LOCALSEND_NOTIFICATION_CMD	(auto)	Custom notification command
LOCALSEND_MAX_BODY_SIZE	0	Max request body size (0 = unlimited)
LOCALSEND_SECURITY_DIR	(auto)	Security context directory
LOCALSEND_FILE_CONFLICT_RESOLUTION	rename	File conflict mode (rename/overwrite/skip)
LOCALSEND_BIND_ADDRESS	(all)	Bind to specific IP address
LOCALSEND_STATIC_PEERS	—	Comma-separated list of static peer IP:port
LOCALSEND_TRUSTED_FINGERPRINTS	—	Comma-separated list of trusted device fingerprints

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
info	Show device information
devices	List discovered devices
history	Show transfer history log
stop	Stop a running daemon
config	Manage configuration (get/set/add/remove/open/unset/list/path)
version	Show version information

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

Firewall Setup

LocalGo uses the configured port for both file transfers and device discovery. The default port is 53317:

• TCP 53317 for HTTP/HTTPS requests and file transfers.
• UDP 53317 for multicast discovery.

Allow these ports on the machine running localgo serve. Restrict the rules to your local network when possible, and do not expose LocalGo directly to the public Internet.

Linux with UFW

Allow the default port from your LAN (replace the subnet if needed):

sudo ufw allow from 192.168.1.0/24 to any port 53317 proto tcp
sudo ufw allow from 192.168.1.0/24 to any port 53317 proto udp
sudo ufw reload

For a host that should accept connections from any local interface, use the included profile:

sudo ufw app update LocalGo
sudo ufw allow LocalGo

Windows

Run PowerShell as Administrator:

New-NetFirewallRule -DisplayName "LocalGo TCP" -Direction Inbound -Protocol TCP -LocalPort 53317 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "LocalGo UDP" -Direction Inbound -Protocol UDP -LocalPort 53317 -Action Allow -Profile Private

macOS

When macOS asks whether localgo may accept incoming connections, choose Allow. If the prompt does not appear, open System Settings > Network > Firewall > Options, add the LocalGo executable, and allow incoming connections.

Custom ports and containers

If you use a custom port, allow that TCP and UDP port instead of 53317 and configure the same port on every participating device. For Docker or Podman without host networking, publish both protocols, for example:

docker run -p 53317:53317/tcp -p 53317:53317/udp \
  ghcr.io/bethropolis/localgo:latest

If discovery still fails after opening the ports, confirm that the host and peer are on the same LAN, multicast is available on the network, and LocalGo is not bound only to an unreachable interface.

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 or report an issue.

License

MIT License - see LICENSE file.