FAQ¶

General¶

What data format does CloudSync use?¶

All document data is stored as JSON-compatible dictionaries. The sync protocol uses MessagePack for wire encoding to minimize bandwidth.

Is CloudSync open source?¶

The client SDKs are open source (MIT license). The relay server is source-available under the Business Source License (BSL 1.1) and converts to Apache 2.0 after 4 years.

What happens if the relay server goes down?¶

CloudSync uses a local-first architecture. All operations continue to work against the local storage. Changes are queued and synced when connectivity is restored.

How large can a document be?¶

Individual documents are limited to 1 MB. For larger payloads, consider splitting data across multiple documents or using the Blob API (Enterprise plan).

Technical¶

Does CloudSync support nested objects?¶

Yes. Documents can contain arbitrarily nested JSON structures. However, conflict resolution operates at the top-level field granularity by default. Enable deep_merge: true in configuration for nested conflict resolution.

Can I use CloudSync without a server?¶

Yes. CloudSync supports peer-to-peer mode where clients connect directly to each other via WebRTC. Enable it with transport="p2p".

What consistency model does CloudSync provide?¶

CloudSync provides strong eventual consistency via operation-based CRDTs. All nodes are guaranteed to converge to the same state after all operations have been delivered, regardless of ordering.

Is data encrypted in transit and at rest?¶

In transit: TLS 1.3 for all connections
At rest: Optional AES-256-GCM encryption. Enable via encryption_key config option.
End-to-end: When E2E encryption is enabled, the relay server cannot read your data.

How does CloudSync handle clock skew?¶

CloudSync uses Hybrid Logical Clocks (HLC) instead of wall-clock time. This ensures correct causal ordering even with significant clock drift between nodes.

Troubleshooting¶

I get `ERR_AUTH_INVALID_KEY` but my key looks correct¶

Ensure there are no trailing whitespace or newline characters
Check that you're using the correct key type (cs_live_ vs cs_test_)
Verify the key hasn't been revoked in the Dashboard

Connection keeps dropping¶

Check firewall rules for WebSocket connections (port 443)
Ensure your proxy/load balancer supports long-lived WebSocket connections
Increase heartbeat_interval if on an unstable network
Check client.status() for the specific disconnect reason

Documents aren't syncing¶

Verify both nodes use the same region
Check that document keys match exactly (keys are case-sensitive)
Ensure client.connect() has been called on both ends
Check logs with log_level="DEBUG"

Next: Contributing →