Skip to content

Quick Start

This guide walks you through setting up your first CloudSync project in under 5 minutes.

1. Get Your API Key

Sign up at the Dashboard and create a new project. Your API key will look like:

cs_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ

Keep your API key secret

Never commit API keys to version control. Use environment variables or a secrets manager.

2. Initialize the Client

import os
from cloudsync import CloudSyncClient

client = CloudSyncClient(
    api_key=os.environ["CLOUDSYNC_API_KEY"],
    region="us-east-1",          # or eu-west-1, ap-southeast-1
    transport="websocket",       # websocket | grpc | mqtt
)

3. Create a Document

Documents are the core data unit in CloudSync. Each document is identified by a unique key and contains a JSON-compatible dictionary.

# Create or open a document
doc = client.document("user:12345:preferences")

# Set fields
doc.set({
    "theme": "dark",
    "notifications": True,
    "language": "en",
    "sidebar_collapsed": False
})

# Read fields
theme = doc.get("theme")
print(theme)  # "dark"

# Update a single field
doc.update("language", "fr")

# Delete a field
doc.delete("sidebar_collapsed")

4. Real-time Sync

@doc.on("change")
def handle_change(event):
    print(f"[{event.origin}] {event.field}: {event.old_value} → {event.value}")

@doc.on("conflict")
def handle_conflict(event):
    print(f"Conflict on '{event.field}', resolved with: {event.resolved_value}")

# Start the connection
client.connect()  # blocks until disconnected

5. Sync Between Two Nodes

Node A (e.g., your backend):

doc = client.document("shared:config")
doc.set({"feature_flags": {"dark_mode": True, "beta_ui": False}})
client.connect()

Node B (e.g., another service):

doc = client.document("shared:config")

@doc.on("sync")
def on_sync(snapshot):
    print(f"Received config: {snapshot.data}")

client.connect()

Both nodes will converge on the same state, even if updates happen simultaneously.

6. Async Usage

import asyncio
from cloudsync import AsyncCloudSyncClient

async def main():
    client = AsyncCloudSyncClient(
        api_key=os.environ["CLOUDSYNC_API_KEY"],
        region="us-east-1"
    )

    doc = await client.document("session:abc")
    await doc.set({"status": "active", "last_seen": "2025-01-12T10:30:00Z"})

    async for event in doc.watch():
        print(event)

asyncio.run(main())

What's Next?

Next: Configuration →