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.

Important

This project is discontinued and will no longer receive updates.

I recommend switching to OpenTubeX, a fork of FreeTube with native, end-to-end encrypted synchronization and support for self-hosted sync servers. OpenTubeX provides a more complete and integrated solution to the problem freetube-sync was created to solve, so I no longer see a reason to continue maintaining this project.

Along with sync being a built-in feature, it also adds a number of other nice QoL features, so I strongly recommend for any FreeTube user to switch to OpenTubeX.

OpenTubeX supports importing data (subscriptions, playlists, watch history, search history, settings) from FreeTube, so migrating from FreeTube to OpenTubeX is easy.

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.