https://github.com/nitrobass24/seedsync
SeedSync - Fast seedbox file synchronization. Modernized fork with Docker-only deployment, Python 3.12
https://github.com/nitrobass24/seedsync
docker file-sync lftp python seedbox self-hosted
Last synced: 2 months ago
JSON representation
SeedSync - Fast seedbox file synchronization. Modernized fork with Docker-only deployment, Python 3.12
- Host: GitHub
- URL: https://github.com/nitrobass24/seedsync
- Owner: nitrobass24
- License: apache-2.0
- Created: 2024-11-30T03:52:55.000Z (over 1 year ago)
- Default Branch: develop
- Last Pushed: 2026-04-30T21:26:41.000Z (2 months ago)
- Last Synced: 2026-04-30T22:09:20.345Z (2 months ago)
- Topics: docker, file-sync, lftp, python, seedbox, self-hosted
- Language: Python
- Homepage:
- Size: 18.4 MB
- Stars: 46
- Watchers: 2
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
SeedSync is a tool to sync files from a remote Linux server (like your seedbox) to your local machine.
It uses LFTP to transfer files fast!
> **Note**: This is a modernized fork of [ipsingh06/seedsync](https://github.com/ipsingh06/seedsync) with updated dependencies and Docker-only deployment.
## Features
* Built on top of [LFTP](http://lftp.tech/), the fastest file transfer program
* Web UI — track and control your transfers from anywhere
* **Multiple path pairs** — sync from multiple remote directories independently
* **Exclude patterns** — filter out unwanted files with glob patterns
* **Multi-select** — select multiple files for bulk queue/stop/delete
* Auto-Queue — only sync the files you want based on pattern matching
* Automatically extract your files after sync
* **Webhook notifications** — HTTP POST on download/extract events
* Delete local and remote files easily
* Dark mode, staging directory, bandwidth limiting, and more
* **Lightweight Docker image** — ~45 MB Alpine-based, multi-arch (amd64/arm64)
* Fully open source!
## Documentation
Full documentation is available at **[nitrobass24.github.io/seedsync](https://nitrobass24.github.io/seedsync/)**
## Quick Start (Docker)
### Using Docker Compose (Recommended)
1. Create a `docker-compose.yml`:
```yaml
services:
seedsync:
image: ghcr.io/nitrobass24/seedsync:latest
container_name: seedsync
ports:
- "8800:8800"
environment:
- PUID=1000 # Your user ID (run 'id' to find)
- PGID=1000 # Your group ID
# - UMASK=002 # Optional: file permission mask (002 for 775/664)
volumes:
- ./config:/config
- /path/to/downloads:/downloads
# Uncomment below to use SSH key authentication
# - ~/.ssh/id_rsa:/home/seedsync/.ssh/id_rsa:ro
restart: unless-stopped
```
2. Start the container:
```bash
docker compose up -d
```
3. Access the web UI at **http://localhost:8800**
### Using Docker Run
```bash
docker run -d \
--name seedsync \
-p 8800:8800 \
-e PUID=1000 \
-e PGID=1000 \
-v /path/to/config:/config \
-v /path/to/downloads:/downloads \
ghcr.io/nitrobass24/seedsync:latest
# Optional: control file permissions with UMASK
# -e UMASK=002 # 775/664 permissions
```
> **SSH Key Auth**: To use key-based authentication, mount your private key:
> `-v ~/.ssh/id_rsa:/home/seedsync/.ssh/id_rsa:ro`
### Unraid
SeedSync is available as a Community Application on Unraid.
1. In the Unraid web UI, go to **Docker → Template Repositories** and add:
```
https://github.com/nitrobass24/unraid-templates
```
2. Go to the **Apps** tab, search for **SeedSync**, and click **Install**.
3. Review the default paths and click **Apply**:
- **Config**: `/mnt/user/appdata/seedsync`
- **Downloads**: `/mnt/user/downloads/seedsync`
4. Access the web UI at `http://:8800`
> **Note**: PUID/PGID default to `99`/`100` (Unraid's `nobody`/`users`), which is correct for most Unraid setups.
## Configuration
On first run, access the web UI and configure:
1. **Remote Server**: Your seedbox SSH hostname/IP
2. **SSH Credentials**: Username and password
3. **Remote Path**: Directory on the seedbox to sync from
4. **Local Path**: Maps to `/downloads` in the container
### Multiple Path Pairs
To sync from multiple remote directories, use **Path Pairs** in Settings. Each pair has its own remote path, local path, auto-queue toggle, and exclude patterns. Path pairs run independent LFTP and scanner instances.
### SSH Key Authentication
To use password-less SSH key authentication:
1. Mount your private key into the container (see volume examples above)
2. In the web UI Settings, enable **"Use password-less key-based authentication"**
3. The password field can be left blank when key auth is enabled
### Bandwidth Limiting
You can limit download speed in Settings under the **Connections** section. The **Bandwidth Limit** field accepts:
- Numeric values in bytes/sec (e.g., `102400` for 100 KB/s)
- Values with suffixes: `K` for KB/s, `M` for MB/s (e.g., `500K`, `2M`)
- `0` or empty for unlimited
## Recommended Workflow
The best way to use SeedSync is with **hard links** and a dedicated completion directory:
1. **Configure your torrent client** (qBittorrent, ruTorrent, etc.) to hard link completed downloads into a separate folder (e.g., `/downloads/complete`). Hard links don't use extra disk space — your originals stay intact for seeding.
2. **Point SeedSync** at the completion directory.
3. **Enable Auto-Queue** and turn on **"Delete remote file after syncing"** in Settings.
This way, each file is downloaded exactly once. After SeedSync syncs it, the hard link is removed from the completion directory, so it's never re-downloaded — even after a container restart. Your originals remain untouched for seeding.
> **Note**: Both directories must be on the same filesystem for hard links to work.
See the [full setup guide](https://nitrobass24.github.io/seedsync/usage#recommended-setup) in the docs for directory layout examples and torrent client configuration.
## Building from Source
```bash
# Clone the repository
git clone https://github.com/nitrobass24/seedsync.git
cd seedsync
# Build and run
make build
make run
# View logs
make logs
```
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `PUID` | 1000 | User ID for file permissions |
| `PGID` | 1000 | Group ID for file permissions |
| `UMASK` | *(unset)* | File permission mask (e.g. `002` for 775/664, `000` for 777/666) |
## Volumes
| Path | Description |
|------|-------------|
| `/config` | Configuration and state files |
| `/downloads` | Download destination directory |
| `/home/seedsync/.ssh/id_rsa` | SSH private key (optional, for key-based auth) |
## Ports
| Port | Description |
|------|-------------|
| 8800 | Web UI |
## Troubleshooting
### View Logs
```bash
docker logs seedsync
```
### Permission Issues
Ensure your `PUID` and `PGID` match your host user:
```bash
id # Shows your UID and GID
```
### SSH Connection Issues
- Verify your seedbox allows SSH connections
- Check that the SSH port is correct (default: 22)
- Ensure your credentials are correct
- If using SSH key auth, ensure the key is mounted at `/home/seedsync/.ssh/id_rsa` (read-only is fine)
### Custom Python Path on Remote Server
If your seedbox has Python 3 installed at a non-standard location (e.g. a custom build in your home directory), set **Remote Python Path** in Settings to the full path to the Python 3 binary. For example: `~/python3/bin/python3`. Leave empty to use the default `python3`.
### Remote Shell Not Found
If you see an error about `/bin/bash` not found, SeedSync will attempt to auto-detect the available shell on your remote server. Check the logs for the detected shell path. If detection fails, create a symlink on the remote server:
```bash
sudo ln -s /usr/bin/bash /bin/bash
```
### SCP Permission Denied (scanner can't copy to /tmp)
If you see `scp: dest open '/tmp/scanfs': Permission denied` in the logs, your remote server doesn't allow writes to `/tmp`. SeedSync copies its scanner utility there by default.
Fix: open the web UI **Settings**, find **Server Script Path**, and change it to a directory you own on the remote server — for example `~` or `~/.local`. Save and restart the container.
### Server Script Path Is a Directory
If you see `Server Script Path '...' is a directory on the remote server`, the configured path overlaps with your sync directory and a folder named `scanfs` already exists there.
Fix:
1. Change **Server Script Path** to a location outside your sync tree (`~` or `~/.local`)
2. Remove the conflicting directory from the remote server: `rm -rf /your/sync/path/scanfs`
3. Restart the container
## Report an Issue
Please report issues on the [issues page](https://github.com/nitrobass24/seedsync/issues).
Include container logs: `docker logs seedsync`
## License
SeedSync is distributed under Apache License Version 2.0.
See [LICENSE.txt](LICENSE.txt) for more information.
---
