freetube-sync
A sync server and CLI client for FreeTube. Syncs local FreeTube data (profiles, playlists, history, settings, search history) to a central server backed by SQLite.
Deploying
Container (recommended)
docker run -p 8080:8080 -e FREETUBE_SYNC_API_KEYS=your-key foundry.fsky.io/architect/freetube-sync
A Quadlet unit file is available at contrib/quadlet/freetube-sync.container for deploying with Podman and systemd.
From source
Requires Go 1.26+ and make.
make
make install
FREETUBE_SYNC_API_KEYS="your-key" freetube-sync serve
You can also use a config file instead of environment variables:
freetube-sync --config /etc/freetube-sync/config.json serve
Usage
The following collections can be synced: profiles, playlists, history, settings, and search-history.
# Push all collections to the server
freetube-sync push --all
# Pull all collections from the server
freetube-sync pull --all
# Push/pull a single collection
freetube-sync push history
freetube-sync pull playlists
# Check sync status
freetube-sync status
Configuration
Both the server and client are configured through a single JSON config file with separate sections. Environment variables can override any config file value.
The default config file location is ~/.config/freetube-sync/config.json. Use --config or -c to specify a different path:
freetube-sync --config /etc/freetube-sync/config.json serve
Config file format
See config.example.json for a starting template. Either section (client and server) can be omitted if not needed (e.g. a server-only deployment doesn't need client).
Environment variable overrides
Environment variables always take precedence over the config file.
Server
| Variable | Default | Description |
|---|---|---|
FREETUBE_SYNC_PORT |
8080 |
TCP port the HTTP server listens on |
FREETUBE_SYNC_BIND |
0.0.0.0 |
Address to bind to |
FREETUBE_SYNC_API_KEYS |
(required) | Comma-separated list of API keys |
FREETUBE_SYNC_DB_PATH |
./freetube-sync.db |
Path to the SQLite database file |
Client
| Variable | Default | Description |
|---|---|---|
FREETUBE_SYNC_SERVER |
(required) | Sync server URL |
FREETUBE_SYNC_API_KEY |
(required) | API key for authentication |
FREETUBE_SYNC_DATA_PATH |
(auto-detected) | Path to FreeTube data directory |
FreeTube's data path is auto-detected per OS if not configured. Each API key operates in its own namespace on the server, so multi-user setups are achieved by issuing separate keys.
License
The code of this project is released under the Unlicense. See the LICENSE file for details.