Skip to content
Eidos Docs

Sync

Eidos follows the Local-First principle. Your data is stored on your local device by default, and sync is treated as an optional tool for backup and collaboration.

Evolution of Sync Solutions

Section titled “Evolution of Sync Solutions”

Eidos offers a progressive sync strategy, allowing you to choose the most suitable method based on your needs:

1. Manual Copy

Section titled “1. Manual Copy”

The most straightforward way is to directly copy the .eidos directory and paste it into the same location on another device. Since all Eidos content (database and files) is fully contained within this directory, manual copying achieves a primitive form of “sync.”

2. Third-party Sync Tools (e.g., Git)

Section titled “2. Third-party Sync Tools (e.g., Git)”

Placing your Space’s physical directory in a Git repository or on a cloud drive (e.g., iCloud, Dropbox) is an acceptable transitional solution, but it is not optimal:

  • Lack of Version Control: SQLite is a binary file, not text, so tools like Git cannot perform fine-grained version comparisons or merges.
  • Repository Size Explosion: Every change to the SQLite file results in Git creating a full historical record of the binary, causing the repository size to explode over time.
  • Low Sync Efficiency: Each sync involves transferring the entire large file. As the database grows, sync speeds will continuously decline.

3. Eidos Native Sync (Graft)

Section titled “3. Eidos Native Sync (Graft)”

To overcome these limitations, Eidos employs a native sync solution based on Graft. It transforms the single db.sqlite3 file into an objectified storage format, enabling more efficient incremental synchronization.

Architecture Overview

Section titled “Architecture Overview”

Eidos synchronizes data across devices using a centralized S3-compatible bucket as a relay. The core of synchronization is the .eidos folder within the space’s physical directory, which contains the complete database version history (.graft) and all static asset files (files).

This design ensures that the directory structure you see on any device is consistent, with the remote bucket serving as a complete cloud mirror of your local physical directory.

                ┌────────────────────────┐
                │    Remote S3 Bucket    │
                │  s3://bucket/my-space/ │
                │ └── .eidos/            │
                │     ├── .graft/        │
                │     └── files/         │
                └──────────┬─────────────┘
                           │
           ┌───────────────┴────────────────┐
           │              Sync              │
 ┌──────────┴─────────────┐      ┌───────────┴────────────┐
 │         macOS          │      │        Windows         │
 │ /Users/mayne/my-space/ │      │ D:\Eidos\my-space\     │
 │ └── .eidos/            │      │ └── .eidos\            │
 │     ├── .graft/        │      │     ├── .graft\        │
 │     └── files/         │      │     └── files\         │
 └────────────────────────┘      └────────────────────────┘

Storage Structure Changes

Section titled “Storage Structure Changes”

The physical storage structure of a Space differs depending on whether sync is enabled. When enabled, Eidos converts the single-file db.sqlite3 into an objectified storage format (stored in the .graft directory) to achieve:

  • Streaming Sync: Only changed data blocks are synchronized, avoiding the need to upload the entire database file.
  • Version Management: Maintains historical snapshots locally, facilitating merging, rollbacks, and conflict detection across devices.

Sync Disabled

Section titled “Sync Disabled”
  • Directorymy-space/
    • Directory.eidos/
      • db.sqlite3 (Database file)
      • Directoryfiles/ (Static assets)
        • …

Sync Enabled

Section titled “Sync Enabled”
  • Directorymy-space/
    • Directory.eidos/
      • Directory.graft/ (VFS storage directory)
        • …
      • Directoryfiles/ (Static assets)
        • …

Conflict Handling

Section titled “Conflict Handling”

Eidos’s synchronization mechanism is based on Graft, and its workflow is very similar to Git. The sync solution is primarily designed for single-user, multi-device switching scenarios and does not have the automatic conflict resolution capabilities of real-time collaborative systems like CRDT.

To reduce conflicts, it is recommended to follow the Pull → Edit → Push pattern when switching devices:

      Device A                 Cloud                  Device B
       (Work)                  (S3)                   (Idle)
        │                       │                       │
     [ Edit ]                   │                       │
        │         Push          │                       │
        └──────────────────────▶│                       │
                                │         Pull          │
        │                       │──────────────────────▶│
        │                       │                    [ Edit ]
        │                       │         Push          │
        │                       │◀──────────────────────┘
  • Pull → Edit: Before starting work, ensure you have pulled the latest changes from other devices.
  • Edit → Push: After finishing work, promptly push your changes to the cloud.
  • Manual Conflict Resolution: If multiple devices modify the same data simultaneously, Graft will identify the conflict and prompt you for manual arbitration.

Sync Providers

Section titled “Sync Providers”

Eidos supports custom sync providers, which you can choose based on your needs:

  • eidos.space (Official Managed): Zero configuration, just log in to your account. Data is stored in an encrypted S3 bucket provided officially, suitable for users seeking convenience.
  • Custom S3-Compatible Service: You can use your own S3 storage (such as AWS S3, Cloudflare R2, MinIO, etc.). This gives you full control over your data, suitable for users with self-hosting needs or existing cloud storage resources.

Learn how to setup a custom sync provider.

Next Steps

Section titled “Next Steps”