Daemon

The Python daemon that performs bidirectional Google Drive synchronization.

Overview

The daemon runs on Linux, macOS, and Windows as a background process (or systemd user service on Linux) and handles:

Watching local directories for changes (via watchdog)
Polling Google Drive for remote changes
Planning and executing sync operations (upload, download, delete)
Detecting and resolving conflicts
Serving an IPC interface over a Unix domain socket

CLI Usage

cloud-drive-sync-daemon [OPTIONS] COMMAND

Global Options

Option	Description
`--config PATH`	Path to `config.toml` (default: `~/.config/cloud-drive-sync/config.toml`)
`--log-level LEVEL`	Override log level: `debug`, `info`, `warning`, `error`

Commands

`start`

Start the sync daemon.

cloud-drive-sync-daemon start              # Daemonize (fork to background, Linux/macOS only)
cloud-drive-sync-daemon start --foreground  # Run in foreground (for development/systemd)
cloud-drive-sync-daemon start --demo        # Run with mock Drive API (no Google account needed)

Flag	Description
`--foreground`	Run in the foreground instead of forking
`--demo`	Use mock Drive client with synthetic test data
`--config PATH`	Path to config file

Windows note: The daemon always runs in foreground mode on Windows (fork is not supported). The Tauri UI manages the daemon lifecycle as a sidecar process.

`stop`

Stop a running daemon by sending SIGTERM.

cloud-drive-sync-daemon stop

`status`

Check whether the daemon is running.

cloud-drive-sync-daemon status
# Output: "Daemon is running (PID 12345)" or "Daemon is not running."

`auth`

Run the OAuth2 authorization flow interactively.

cloud-drive-sync-daemon auth
# Output: "Authorization successful. Credentials stored and ready to use."

Configuration Reference

The daemon reads configuration from a platform-specific path (or the path specified by --config). All values have sensible defaults.

Platform	Default config path
Linux	`~/.config/cloud-drive-sync/config.toml`
macOS	`~/Library/Application Support/cloud-drive-sync/config.toml`
Windows	`%APPDATA%\cloud-drive-sync\config.toml`

`[general]`

Key	Type	Default	Description
`log_level`	string	`"info"`	Logging level: `debug`, `info`, `warning`, `error`

`[sync]`

Key	Type	Default	Description
`poll_interval`	integer	`30`	Seconds between remote change polls
`conflict_strategy`	string	`"keep_both"`	How to handle conflicts: `keep_both`, `newest_wins`, `ask_user`
`max_concurrent_transfers`	integer	`4`	Max simultaneous upload/download operations
`debounce_delay`	float	`1.0`	Seconds to wait before processing a local change (coalesces rapid edits)

`[[sync.pairs]]`

Each [[sync.pairs]] entry defines a local-to-remote folder mapping.

Key	Type	Default	Description
`local_path`	string	(required)	Absolute path to the local directory
`remote_folder_id`	string	`"root"`	Google Drive folder ID (`"root"` = My Drive top level)
`enabled`	boolean	`true`	Whether this pair should be synced
`sync_mode`	string	`"two_way"`	Sync direction: `"two_way"`, `"upload_only"`, or `"download_only"`
`ignore_hidden`	boolean	`true`	Whether to exclude hidden files/directories (names starting with `.`) from sync

Example Configuration

[general]
log_level = "info"

[sync]
poll_interval = 30
conflict_strategy = "keep_both"
max_concurrent_transfers = 4
debounce_delay = 1.0

[[sync.pairs]]
local_path = "/home/user/Documents"
remote_folder_id = "root"
enabled = true
sync_mode = "two_way"
ignore_hidden = true

[[sync.pairs]]
local_path = "/home/user/Pictures"
remote_folder_id = "0A3xRemoteFolderIdHere"
enabled = true
sync_mode = "upload_only"
ignore_hidden = true

Demo Mode

Demo mode runs the full daemon with a mock Drive client instead of connecting to Google's API:

cloud-drive-sync-daemon start --foreground --demo

What demo mode does:

Creates a temporary local sync directory with sample files
Simulates remote files and changes
Processes sync operations (upload/download/conflict) against the mock backend
Responds to all IPC commands normally

This allows the UI to be fully tested without a Google account or network access.

Headless Authentication

The --headless flag disables automatic browser opening. Instead, the daemon prints a URL or code to the console, and you complete authorization on any device with a browser (your phone, a laptop, etc.). This works over SSH, in Docker containers, and on servers without a display.

Google Drive

cloud-drive-sync account add --provider gdrive --headless

What happens:

The daemon prints an authorization URL
Open that URL in any browser (on your phone, another computer, etc.)
Sign in with your Google account and click "Allow"
Google redirects to http://localhost?code=... — this page won't load (that's normal)
Copy the full URL from your browser's address bar and paste it back into the terminal
The daemon extracts the code and completes authorization

Output looks like:

Visit this URL to authorize:

  https://accounts.google.com/o/oauth2/auth?client_id=...&scope=...

Sign in, click 'Allow'.
Your browser will redirect to a localhost URL that won't load.
Copy the FULL URL from your browser's address bar and paste it here.

Paste the redirect URL (or just the code): http://localhost?code=4/0A...

Via the Web UI

When using the web UI (e.g., http://localhost:8080/ or behind a reverse proxy):

Go to the Accounts tab and click Add Account
A "Sign in with Google" button appears — click it to open the auth page
Sign in and click "Allow"
Your browser redirects to a localhost page that won't load — that's expected
Copy the entire URL from your browser's address bar (it contains ?code=...)
Paste it into the input field in the web UI and click Complete Setup

This works regardless of domain, port, or reverse proxy configuration.

OneDrive

cloud-drive-sync account add --provider onedrive --headless

What happens:

The daemon prints a device code and a verification URL
Open https://microsoft.com/devicelogin on any device
Enter the code shown in the terminal
Sign in with your Microsoft account and approve
The daemon detects the approval automatically (polls in the background)

Output looks like:

To sign in, use a web browser to open https://microsoft.com/devicelogin
and enter the code ABCD-EFGH to authenticate.

This is the most Docker-friendly flow — no redirect needed.

Dropbox

cloud-drive-sync account add --provider dropbox --headless

What happens:

The daemon prints an authorization URL
Open that URL in any browser and click "Allow"
Dropbox shows an authorization code on screen
Copy the code and paste it back into the terminal

Output looks like:

1. Go to: https://www.dropbox.com/oauth2/authorize?...
2. Click 'Allow' (you might have to log in first)
3. Copy the authorization code.

Enter the authorization code: _

Nextcloud

Via the UI (recommended): Select "Nextcloud" in the Account Manager, fill in your server URL, username, and app password, then click Connect. No browser or terminal prompts needed.

Via CLI:

cloud-drive-sync account add --provider nextcloud --headless

The CLI prompts interactively for server URL, username, and app password (requires a TTY).

Creating an app password: In Nextcloud, go to Settings → Security → Devices & sessions → create a new app-specific password. Use that password — not your regular login password.

Box

cloud-drive-sync account add --provider box --headless

What happens:

The daemon prints an authorization URL
Open that URL in any browser and sign in to Box
Box shows an authorization code
Paste it back into the terminal

Docker Usage

The recommended way to add accounts in Docker is via the HTTP web UI at http://localhost:8080:

Google Drive / Dropbox / OneDrive / Box: Click "Add Account", complete the OAuth browser flow using the provided URL, then paste the redirect URL back.
Nextcloud: Select Nextcloud, fill in the server URL + username + app password form, click Connect. No TTY needed.

For Google Drive via CLI (requires -it for the OAuth URL prompt):

# Start the daemon
docker run -d --name cloud-drive-sync \
  -p 8080:8080 \
  -v cloud-drive-sync-config:/root/.config/cloud-drive-sync \
  -v cloud-drive-sync-data:/root/.local/share/cloud-drive-sync \
  -v ~/Documents:/data/Documents \
  ghcr.io/ciberkids/cloud-drive-sync:latest

# Add Google account via CLI (prints auth URL, paste redirect URL back)
docker exec -it cloud-drive-sync \
  python -m cloud_drive_sync account add --provider gdrive --headless

# Verify it worked
docker exec cloud-drive-sync python -m cloud_drive_sync account list

After adding accounts, the daemon syncs automatically — no restart needed.

Docker Deployment

The daemon runs headless in Docker with no GUI dependencies.

Quick Start

docker run -d --name cloud-drive-sync \
  -p 8080:8080 \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  -v cloud-drive-sync-config:/root/.config/cloud-drive-sync \
  -v cloud-drive-sync-data:/root/.local/share/cloud-drive-sync \
  -v ~/Documents:/data/Documents \
  ghcr.io/ciberkids/cloud-drive-sync:latest

# Open http://localhost:8080/ for the web management UI

# Add account (interactive — prints auth URL)
docker exec -it cloud-drive-sync \
  python -m cloud_drive_sync account add --provider gdrive --headless

# Check status
docker exec cloud-drive-sync python -m cloud_drive_sync status

File Ownership (PUID / PGID)

By default the daemon runs as root inside the container, which causes synced files in bind-mounted folders to be owned by root on the host. Set PUID and PGID to your host user's numeric IDs to have the daemon run as that user and write files with the correct ownership:

docker run -d \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  ...

Or in docker-compose.yml:

environment:
  - PUID=1000   # host user ID (id -u)
  - PGID=1000   # host group ID (id -g)

Config and data volumes (/root/.config/cloud-drive-sync and /root/.local/share/cloud-drive-sync) are automatically chowned to PUID:PGID on startup so no manual volume permission changes are needed. Omitting PUID/PGID (or setting PUID=0) preserves the legacy root behaviour.

HTTP REST API

The daemon can expose an HTTP REST API with a built-in web UI for headless and Docker management.

Enable with the --http-port flag: cloud-drive-sync-daemon start --foreground --http-port 8080
Docker containers enable it by default on port 8080.
Web UI: http://localhost:8080/
REST API: http://localhost:8080/api/*

Endpoints

Status

Method	Path	Description
GET	`/api/status`	Daemon and sync status

Accounts

Method	Path	Description
GET	`/api/accounts`	List all accounts
POST	`/api/accounts`	Add a new account (OAuth or Nextcloud credentials)
POST	`/api/accounts/auth-code`	Exchange OAuth authorization code
GET	`/api/accounts/oauth-callback`	OAuth redirect callback handler
DELETE	`/api/accounts/{email}`	Remove an account
PUT	`/api/accounts/{email}/max-transfers`	Set per-account max concurrent transfers

Sync Pairs

Method	Path	Description
GET	`/api/pairs`	List sync pairs
POST	`/api/pairs`	Add a sync pair (`local_path`, `remote_folder_id`, `provider`, `account_id`, `sync_mode`)
DELETE	`/api/pairs/{pair_id}`	Remove a sync pair
PUT	`/api/pairs/{pair_id}/mode`	Set sync mode (`two_way` / `upload_only` / `download_only`)
PUT	`/api/pairs/{pair_id}/ignore-hidden`	Toggle dotfile exclusion
PUT	`/api/pairs/{pair_id}/ignore-patterns`	Set glob ignore patterns
GET	`/api/pairs/{pair_id}/rules`	Get advanced sync rules (size limit, regex filters)
PUT	`/api/pairs/{pair_id}/rules`	Set advanced sync rules

Sync Control

Method	Path	Description
POST	`/api/sync`	Trigger an immediate sync (optional `pair_id`)
POST	`/api/sync/pause`	Pause sync (optional `pair_id`)
POST	`/api/sync/resume`	Resume sync (optional `pair_id`)

Conflicts & Activity

Method	Path	Description
GET	`/api/conflicts`	List unresolved conflicts
POST	`/api/conflicts/{conflict_id}/resolve`	Resolve a conflict
GET	`/api/activity`	Recent sync activity log (`?limit=N&offset=N`)

Settings

Method	Path	Description
GET/PUT	`/api/settings/notifications`	Notification preferences
GET/PUT	`/api/settings/bandwidth`	Upload/download bandwidth limits (kbps, 0 = unlimited)
GET/PUT	`/api/settings/proxy`	HTTP/HTTPS proxy settings
PUT	`/api/settings/conflict-strategy`	Conflict strategy (`keep_both` / `newest_wins` / `ask_user`)

File Browser (headless)

Method	Path	Description
GET	`/api/remote-folders`	List remote folders (`?parent_id=&account_id=`)
POST	`/api/remote-folders`	Create a remote folder
GET	`/api/local-dirs`	List local directories (`?path=`)
POST	`/api/local-dirs`	Create a local directory

Adding accounts via Web UI

When you click Add Account in the web UI, the daemon runs the headless auth flow in the background. Since the auth prompts appear in the daemon's stdout (not in the browser), follow these steps:

Click Add Account in the web UI — the button shows "Authenticating..."

In another terminal, check the daemon logs for the authorization URL:

# Docker
docker logs -f cloud-drive-sync

# Docker Compose
docker compose logs -f daemon

# Local
# The URL prints directly in the terminal running the daemon

Open the authorization URL in your browser and complete sign-in
The web UI updates automatically when auth completes

Example curl commands

# Check status
curl http://localhost:8080/api/status

# List accounts
curl http://localhost:8080/api/accounts

# Add account (headless)
curl -X POST http://localhost:8080/api/accounts \
  -H "Content-Type: application/json" \
  -d '{"provider": "gdrive", "headless": true}'

# List sync pairs
curl http://localhost:8080/api/pairs

# Trigger a sync
curl -X POST http://localhost:8080/api/sync

# Get recent activity
curl 'http://localhost:8080/api/activity?limit=20'

# Set bandwidth limits
curl -X PUT http://localhost:8080/api/settings/bandwidth \
  -H "Content-Type: application/json" \
  -d '{"max_upload_kbps": 1000, "max_download_kbps": 2000}'

Docker Compose

See docker/docker-compose.yml for a ready-to-use compose file.

Volumes

Mount	Purpose
`/root/.config/cloud-drive-sync`	Config (config.toml)
`/root/.local/share/cloud-drive-sync`	Credentials, database
`/run/cloud-drive-sync`	IPC socket (for CLI from host)
`/data/*`	Sync folder mount points

Environment Variables

Variable	Default	Description
`XDG_RUNTIME_DIR`	`/run/cloud-drive-sync`	IPC socket directory
`CDS_GOOGLE_CLIENT_ID`	(embedded)	Override Google OAuth client ID
`CDS_GOOGLE_CLIENT_SECRET`	(embedded)	Override Google OAuth client secret

Logging and Disk Usage

The daemon writes to <data-dir>/cloud-drive-sync.log and to stderr. Both are bounded, so neither can grow without limit:

Limit	Value	Notes
Log file size	10 MB	Rotated in place, oldest discarded
Rotated copies kept	5	Total log footprint therefore caps at ~60 MB
Maximum message length	2000 characters	Longer messages are truncated with the original length appended

Message truncation matters because provider exceptions embed the full failed request in their text. Without a cap, a single rejected WebDAV request could write a ~440 KB line, and repeated retries wrote it again each time. The diagnostic part of a message — action, path, status code — is always at the front, so truncation never removes it. Tracebacks are not truncated.

Rotated files are named cloud-drive-sync.log.1 through .5. To keep long-term history, ship the log elsewhere (journald, a log collector, or a logrotate rule on a copy) rather than relying on the daemon's own files.

Database maintenance

The sync state database at <data-dir>/state.db maintains itself, so it does not need manual VACUUMing.

Behaviour	Value
Activity log retention	30 days
Maintenance interval	6 hours
Startup reclaim threshold	25% of the file free and at least 64 MB reclaimable

Two things run automatically:

Every 6 hours, activity-log rows older than 30 days are deleted and the freed pages are returned to the filesystem. Pruning is bounded per run, so the first pass on a large history is spread over several runs rather than blocking. Activity older than 30 days will therefore disappear from the Activity view — export it first if you need to keep it.
At startup, if the file is mostly wasted space, it is rewritten to reclaim it. SQLite does not shrink a database when rows are deleted: freed pages go on an internal free list and get reused, so a long-running daemon's file only ever grows. Databases created before this behaviour existed could reach several GB while holding no rows at all; the first start after upgrading reclaims that and logs the before/after size.

The startup reclaim is deliberately rare because it rewrites the whole file and delays startup while it runs. New databases are created with incremental auto-vacuum enabled, so they give space back continuously and should never reach the threshold.

Stub Repair

Stubs are incomplete sync-state entries that accumulate when a transfer is interrupted or the sync database is reset while remote files still exist. They show up as files tracked in the database that are missing on one side, causing repeated, fruitless sync attempts.

Scanning for stubs

In the web UI, open Settings, expand a sync pair, and click Scan for stubs. The daemon checks the database against the live local and remote file lists and reports how many stale entries it found.

Via the REST API:

# Dry-run scan (no changes)
curl -X POST 'http://localhost:8080/api/pairs/0/repair?dry_run=true'

# Apply the repair (deletes stale DB entries)
curl -X POST 'http://localhost:8080/api/pairs/0/repair'

When to use it

After a container restart or database migration where the DB was re-created
If the activity log shows repeated errors for the same file that does not exist locally
After manually deleting files outside of the sync process
After an rclone bisync --resync or equivalent baseline reset on the remote side

Stub repair only removes database records — it never deletes files from local storage or from the cloud.

Development

Setup

cd daemon
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run in Development

# With real Drive API
python -m cloud_drive_sync --log-level debug start --foreground

# With demo mode
python -m cloud_drive_sync start --foreground --demo

Run Tests

pytest -v
pytest --cov=cloud_drive_sync  # With coverage

Lint

ruff check src/ tests/

Architecture

The daemon is structured as a set of asyncio components:

Daemon
  ├── Config (TOML loader)
  ├── Database (async SQLite via aiosqlite)
  ├── DriveClient (Google API v3 wrapper)
  ├── SyncEngine
  │     ├── DirectoryWatcher (per pair, watchdog-based)
  │     ├── ChangePoller (per pair, Drive Changes API)
  │     ├── SyncPlanner (diff + action planning)
  │     ├── SyncExecutor (concurrent transfer runner)
  │     └── ConflictResolver (strategy dispatch)
  └── IpcServer (Unix socket, JSON-RPC 2.0)
        └── RequestHandler (method dispatch)

For full architectural details, see the Architecture page.

Dependencies

Package	Version	Purpose
google-api-python-client	>=2.100.0	Google Drive API v3
google-auth-oauthlib	>=1.1.0	OAuth2 flow
google-auth-httplib2	>=0.2.0	HTTP transport for Google auth
watchdog	>=4.0.0	Filesystem event monitoring
aiosqlite	>=0.19.0	Async SQLite
aiofiles	>=23.2.0	Async file I/O
tomli-w	>=1.0.0	TOML writing
click	>=8.1.0	CLI framework
cryptography	>=41.0.0	Credential encryption

Dev Dependencies

Package	Version	Purpose
pytest	>=7.4.0	Test framework
pytest-asyncio	>=0.21.0	Async test support
pytest-cov	>=4.1.0	Coverage reporting
ruff	>=0.1.0	Linter and formatter

Cloud Drive Sync | Report an Issue | Releases

Cloud Drive Sync

Home

Getting Started

Reference

Project

Daemon

Daemon

Overview

CLI Usage

Global Options

Commands

start

stop

status

auth

Configuration Reference

[general]

[sync]

[[sync.pairs]]

Example Configuration

Demo Mode

Headless Authentication

Google Drive

Via the Web UI

OneDrive

Dropbox

Nextcloud

Box

Docker Usage

Docker Deployment

Quick Start

File Ownership (PUID / PGID)

HTTP REST API

Endpoints

Adding accounts via Web UI

Example curl commands

Docker Compose

Volumes

Environment Variables

Logging and Disk Usage

Database maintenance

Stub Repair

Scanning for stubs

When to use it

Development

Setup

Run in Development

Run Tests

Lint

Architecture

Dependencies

Dev Dependencies

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

`start`

`stop`

`status`

`auth`

`[general]`

`[sync]`

`[[sync.pairs]]`