{"id":31051733,"url":"https://github.com/bethropolis/localgo","last_synced_at":"2025-10-09T03:40:22.475Z","repository":{"id":303272761,"uuid":"1014918328","full_name":"bethropolis/localgo","owner":"bethropolis","description":"a golang implementation of the localsend protocol","archived":false,"fork":false,"pushed_at":"2025-07-06T17:52:52.000Z","size":70,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T17:43:35.366Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bethropolis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-06T16:58:07.000Z","updated_at":"2025-09-01T15:48:28.000Z","dependencies_parsed_at":"2025-07-06T18:42:35.915Z","dependency_job_id":"76e94af1-f79e-45c6-948e-046c7f5eb333","html_url":"https://github.com/bethropolis/localgo","commit_stats":null,"previous_names":["bethropolis/localgo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bethropolis/localgo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethropolis%2Flocalgo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethropolis%2Flocalgo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethropolis%2Flocalgo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethropolis%2Flocalgo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bethropolis","download_url":"https://codeload.github.com/bethropolis/localgo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bethropolis%2Flocalgo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000714,"owners_count":26082911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-15T00:52:01.838Z","updated_at":"2025-10-09T03:40:22.457Z","avatar_url":"https://github.com/bethropolis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LocalGo\n\nA Go implementation of the LocalSend protocol for secure, cross-platform file sharing.\n\n[![Go Version](https://img.shields.io/badge/Go-1.19+-blue.svg)](https://golang.org)\n[![Protocol](https://img.shields.io/badge/Protocol-LocalSend%20v2.1-green.svg)](https://github.com/localsend/protocol)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n## 🚀 Features\n\n### Core Functionality\n- ✅ **Complete LocalSend v2.1 Protocol** - Full compatibility with LocalSend ecosystem\n- ✅ **Secure File Transfer** - HTTPS with self-signed certificates and PIN protection\n- ✅ **Multi-Platform Discovery** - Multicast UDP + HTTP fallback for reliable device detection\n- ✅ **Cross-Platform** - Works on Linux, macOS, and Windows\n- ✅ **High Performance** - Efficient file transfer with progress tracking\n\n## 📦 Quick Start\n\n### Installation\n\n**Option 1: One-command installation (Recommended)**\n```bash\n# User installation\n./scripts/install.sh\n\n# System-wide with service\nsudo ./scripts/install.sh --mode system --service --create-user\n```\n\n**Option 2: Manual build**\n```bash\ngit clone https://github.com/bethropolis/localgo.git\ncd localgo\nmake build\n```\n\n**Option 3: Go global install**\n```bash\ngo install github.com/bethropolis/localgo/cmd/localgo-cli@latest\n```\n\n### Basic Usage\n\n```bash\n# Start server to receive files\nlocalgo-cli serve\n\n# Discover devices on network\nlocalgo-cli discover\n\n# Send a file\nlocalgo-cli send --file document.pdf --to \"John's Phone\"\n\n# Get help\nlocalgo-cli help\nlocalgo-cli help send\n```\n\n## 📖 Usage Guide\n\n### Starting the Server\n\n```bash\n# Basic server (HTTPS on port 53317)\nlocalgo-cli serve\n\n# Custom configuration\nlocalgo-cli serve --port 8080 --http --alias \"MyServer\" --pin 123456\n\n# With environment variables\nexport LOCALSEND_ALIAS=\"File Server\"\nexport LOCALSEND_DOWNLOAD_DIR=\"/srv/files\"\nlocalgo-cli serve\n```\n\n### Sending Files\n\n```bash\n# Send to specific device\nlocalgo-cli send --file presentation.pptx --to \"MacBook Pro\"\n\n# Send with custom timeout\nlocalgo-cli send --file large-video.mp4 --to \"Desktop\" --timeout 300\n\n# Send with custom sender alias\nlocalgo-cli send --file report.pdf --to \"Office PC\" --alias \"Mobile Device\"\n```\n\n### Discovery and Scanning\n\n```bash\n# Discover devices (multicast)\nlocalgo-cli discover --timeout 10\n\n# Scan network (HTTP)\nlocalgo-cli scan --port 53317\n\n# JSON output for scripting\nlocalgo-cli discover --json | jq '.devices[].alias'\n\n# Quiet mode for automation\nlocalgo-cli scan --quiet --timeout 5\n```\n\n### Device Information\n\n```bash\n# Show device configuration\nlocalgo-cli info\n\n# JSON format for scripts\nlocalgo-cli info --json\n\n# Check version\nlocalgo-cli version\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n```bash\n# Device Configuration\nLOCALSEND_ALIAS=\"My Device\"              # Device name\nLOCALSEND_PORT=53317                     # Server port\nLOCALSEND_DOWNLOAD_DIR=\"./downloads\"     # Download directory\nLOCALSEND_DEVICE_TYPE=\"desktop\"          # Device type\n\n# Network Configuration\nLOCALSEND_MULTICAST_GROUP=\"224.0.0.167\" # Multicast address\nLOCALSEND_FORCE_HTTP=false               # Use HTTP instead of HTTPS\n\n# Security Configuration\nLOCALSEND_PIN=\"123456\"                   # PIN for authentication\nLOCALSEND_SECURITY_DIR=\"./.localgo_security\" # Security files location\n\n# Logging Configuration\nLOCALSEND_LOG_LEVEL=\"info\"               # Log level (debug,info,warn,error)\nLOCALSEND_VERBOSE=false                  # Verbose output\nLOCALSEND_NO_COLOR=false                 # Disable colored output\n```\n\n### Configuration File\n\nCreate `localgo.env`:\n```bash\n# Copy example configuration\ncp scripts/localgo.env.example localgo.env\n\n# Edit configuration\neditor localgo.env\n\n# Use configuration\nsource localgo.env \u0026\u0026 localgo-cli serve\n```\n\n### Command-Line Flags\n\nEach command supports specific flags:\n\n```bash\n# Serve command\nlocalgo-cli serve --port 8080 --http --pin 123456 --alias \"Server\" --dir \"/tmp\" --verbose\n\n# Send command\nlocalgo-cli send --file data.zip --to \"Device\" --port 8080 --timeout 60 --alias \"Sender\"\n\n# Discovery commands\nlocalgo-cli discover --timeout 10 --json --quiet\nlocalgo-cli scan --port 8080 --timeout 15 --json\n```\n\n## 🔧 System Service\n\n### Installation\n\n```bash\n# Install as system service\nsudo ./scripts/install.sh --mode system --service --create-user\n```\n\n### Service Management\n\n```bash\n# Enable and start service\nsudo systemctl enable localgo\nsudo systemctl start localgo\n\n# Check status\nsudo systemctl status localgo\n\n# View logs\nsudo journalctl -u localgo -f\n\n# Restart service\nsudo systemctl restart localgo\n```\n\n### Service Configuration\n\nEdit `/etc/localgo/localgo.env`:\n```bash\nLOCALSEND_ALIAS=\"File Server\"\nLOCALSEND_PORT=53317\nLOCALSEND_DOWNLOAD_DIR=\"/srv/localgo/downloads\"\nLOCALSEND_PIN=\"secure123\"\nLOCALSEND_DEVICE_TYPE=\"server\"\n```\n\n## 🤖 Automation \u0026 Scripting\n\n### JSON Output\n\nPerfect for integration with other tools:\n\n```bash\n# Get device list\nDEVICES=$(localgo-cli scan --json --timeout 5)\necho \"$DEVICES\" | jq -r '.devices[].alias'\n\n# Check if service is running\nlocalgo-cli info --json | jq -r '.alias + \" on port \" + (.port|tostring)'\n\n# Monitor file transfers\nlocalgo-cli info --json | jq '.downloadDir'\n```\n\n### Batch Operations\n\n```bash\n# Send multiple files\nfind /uploads -name \"*.pdf\" | while read file; do\n    localgo-cli send --file \"$file\" --to \"PrintServer\"\ndone\n\n# Health check script\n#!/bin/bash\nif localgo-cli info --json \u003e/dev/null 2\u003e\u00261; then\n    echo \"LocalGo is healthy\"\n    exit 0\nelse\n    echo \"LocalGo is not responding\"\n    exit 1\nfi\n```\n\n### Docker Integration\n\n```dockerfile\nFROM golang:1.19-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN make build\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nWORKDIR /root/\nCOPY --from=builder /app/localgo-cli .\nCOPY scripts/localgo.env.example localgo.env\nCMD [\"./localgo-cli\", \"serve\"]\n```\n\n## 💻 Development\n\n### Building\n\n```bash\n# Build binary\nmake build\n\n# Run tests\nmake test\n\n# Run with coverage\nmake test-coverage\n\n# Clean build artifacts\nmake clean\n```\n\n### Project Structure\n\n```\nlocalgo/\n├── cmd/localgo-cli/           # CLI application entry point\n├── pkg/                       # Core library packages\n│   ├── cli/                  # CLI output utilities\n│   ├── config/               # Configuration management\n│   ├── crypto/               # TLS certificates and fingerprints\n│   ├── discovery/            # Network discovery (multicast + HTTP)\n│   ├── httputil/             # HTTP response utilities\n│   ├── logging/              # Structured logging\n│   ├── model/                # Data structures (Device, File, DTOs)\n│   ├── network/              # Network interface utilities\n│   ├── send/                 # File sending logic\n│   ├── server/               # HTTP server and handlers\n│   └── storage/              # File storage management\n├── scripts/                  # Installation and utility scripts\n├── protocol/                 # LocalSend protocol specification\n└── downloads/                # Default download directory\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `make test`\n5. Submit a pull request\n\n## 🌟 Examples\n\n### Home Media Server\n\n```bash\n# Configure as media server\nexport LOCALSEND_ALIAS=\"Home Media Server\"\nexport LOCALSEND_DOWNLOAD_DIR=\"/media/shared\"\nexport LOCALSEND_DEVICE_TYPE=\"server\"\nexport LOCALSEND_PIN=\"family123\"\n\n# Install as system service\nsudo ./scripts/install.sh --mode system --service --create-user\n\n# Start service\nsudo systemctl start localgo\n```\n\n### Development Setup\n\n```bash\n# Configure for development\nexport LOCALSEND_ALIAS=\"Dev-$(whoami)\"\nexport LOCALSEND_PORT=8080\nexport LOCALSEND_FORCE_HTTP=true\nexport LOCALSEND_VERBOSE=true\nexport LOCALSEND_LOG_LEVEL=\"debug\"\n\n# Start with verbose logging\nlocalgo-cli serve --verbose\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions example\n- name: Test file transfer\n  run: |\n    # Start receiver\n    localgo-cli serve --http --port 8080 \u0026\n    sleep 2\n\n    # Send test file\n    echo \"test data\" \u003e test.txt\n    localgo-cli send --file test.txt --to \"$(localgo-cli info --json | jq -r '.alias')\"\n\n    # Verify transfer\n    test -f downloads/test.txt\n```\n\n### Network Monitoring\n\n```bash\n#!/bin/bash\n# Monitor LocalGo devices on network\n\nwhile true; do\n    echo \"=== LocalGo Network Scan $(date) ===\"\n    localgo-cli scan --json --timeout 10 | jq -r '\n        .devices[] |\n        \"\\(.alias) (\\(.deviceType)) - \\(.ip):\\(.port) - \\(.protocol)\"\n    '\n    echo\n    sleep 60\ndone\n```\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n**Port already in use:**\n```bash\n# Check what's using the port\nsudo netstat -tlnp | grep 53317\n\n# Use different port\nlocalgo-cli serve --port 8080\n```\n\n**Discovery not working:**\n```bash\n# Check firewall\nsudo ufw status\n\n# Test network connectivity\nlocalgo-cli scan --timeout 10\n\n# Use HTTP discovery\nlocalgo-cli scan --json\n```\n\n**Permission denied:**\n```bash\n# Fix download directory permissions\nsudo chown -R $USER:$USER ~/Downloads/LocalGo\n\n# Check service user permissions (systemd)\nsudo journalctl -u localgo -n 50\n```\n\n### Debug Mode\n\n```bash\n# Enable verbose logging\nlocalgo-cli serve --verbose\n\n# Debug network issues\nexport LOCALSEND_LOG_LEVEL=\"debug\"\nlocalgo-cli discover\n```\n\n## 📋 Protocol Compliance\n\nLocalGo implements the complete LocalSend v2.1 protocol:\n\n- ✅ **Discovery API** - `/api/localsend/v2/register`, `/api/localsend/v2/info`\n- ✅ **Upload API** - `/api/localsend/v2/prepare-upload`, `/api/localsend/v2/upload`\n- ✅ **Download API** - `/api/localsend/v2/prepare-download`, `/api/localsend/v2/download`\n- ✅ **Session Management** - Proper session handling with tokens and timeouts\n- ✅ **Security** - TLS encryption, fingerprint validation, PIN protection\n- ✅ **Discovery** - Multicast UDP announcements with HTTP fallback\n\n## 📜 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [LocalSend Project](https://github.com/localsend/localsend) - For the excellent protocol specification\n- [LocalSend Protocol](https://github.com/localsend/protocol) - For detailed protocol documentation\n\n## 🔗 Related Projects\n\n- [LocalSend](https://github.com/localsend/localsend) - Original Flutter implementation\n- [LocalSend_rs](https://github.com/notjedi/localsend-rs) - A cli Rust implementation\n\n---\nthank you\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbethropolis%2Flocalgo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbethropolis%2Flocalgo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbethropolis%2Flocalgo/lists"}