1
1
Fork
You've already forked cs-sync-server
0
Cloudstream3 Sync Server
  • Python 98.4%
  • Dockerfile 1.6%
Find a file
2026年06月25日 22:36:30 +03:00
app Fix race condition with atomic SQLite upserts 2026年06月25日 22:36:30 +03:00
.env.example Beta release 2026年06月25日 22:03:21 +03:00
.gitignore Beta release 2026年06月25日 22:03:21 +03:00
docker-compose.yml Beta release 2026年06月25日 22:03:21 +03:00
Dockerfile Beta release 2026年06月25日 22:03:21 +03:00
README.md Beta release 2026年06月25日 22:03:21 +03:00
requirements.txt Beta release 2026年06月25日 22:03:21 +03:00

CloudStream Sync Server

Self-hosted sync server for CloudStream 3. Syncs bookmarks, resume watching, search history, settings, and extension repositories across devices.

Features

  • REST API with Bearer token authentication
  • Per-category sync (extensions, bookmarks, resume watching, search history, settings)
  • Device management (register, list, delete)
  • SQLite backend (zero-config, file-based)
  • Admin API for token CRUD

Requirements

  • Python 3.11+
  • pip / uv

Quick Start

cd cs-sync-server
pip install -r requirements.txt
# Configure
export CS_SYNC_ADMIN_KEY="your-admin-secret"
export CS_SYNC_ALLOWED_OPEN_REGISTRATION=true
# Run
python -m uvicorn app.main:app --host 0.0.0.0 --port 8400

The server creates sync.db automatically on first run.

Configuration

All settings via environment variables (prefix CS_SYNC_):

Variable Default Description
CS_SYNC_ADMIN_KEY — Admin API key for token management. Required.
CS_SYNC_ALLOWED_OPEN_REGISTRATION false If true, new tokens auto-register on first use
CS_SYNC_DB_PATH sync.db SQLite database file path
CS_SYNC_HOST 0.0.0.0 Bind host
CS_SYNC_PORT 8400 Bind port

API Reference

Health

GET /v1/health

Admin (requires X-Admin-Key header)

Method Endpoint Description
POST /v1/admin/tokens/{token} Create a new sync token
GET /v1/admin/tokens List all tokens
DELETE /v1/admin/tokens/{token} Delete token + all its data

Sync (requires Authorization: Bearer {token})

Method Endpoint Description
GET /v1/sync/manifest Get manifest (timestamps + hashes per category)
PUT /v1/sync/categories/{key} Push category data (gzip-compressed JSON)
GET /v1/sync/categories/{key} Pull category data
GET /v1/sync/devices List devices
PUT /v1/sync/devices/{deviceId} Register/update device
DELETE /v1/sync/devices/{deviceId} Delete device

Categories: extensions, bookmarks, resume_watching, search_history, settings

Docker

docker build -t cs-sync-server .
docker run -p 8400:8400 -e CS_SYNC_ADMIN_KEY=secret cs-sync-server

Architecture

cs-sync-server/
 app/
 main.py # FastAPI routes
 config.py # Environment configuration
 database.py # SQLAlchemy models (Token, Device, Category, Manifest)
 store.py # Async data access layer
 auth.py # Token validation dependencies
 requirements.txt
 Dockerfile