Synchronicity

Overview

Synchronicity is a decentralized personal server implemented as an overlay operating system.

What does this mean in practice? A personal server is a computer owned and controlled by a single person that performs computational tasks on a network on their behalf, where a computational task is concretely something like storing and displaying PDF documents, recording text notes, playing music files, downloading and storing files from the internet, making and recording posts on social media networks, and in general anything that a person might want to do using modern networked computer or smartphone.

decentralized means that there is not a single instantiation of Synchronicity on any particular hardware device; but rather any person's computer is comprised of an ensemble of individual nodes which communicate and synchronize data with each other over the network. Concretely, a node might be an Android smartphone, a desktop or laptop computer, or a Linux VPS in the cloud.

An overlay operating system is a self-contained computing environment designed to be run as a program on an existing computer operating system, instead of directly controlling the hardware itself. A web browser with its Javascript engine capable of executing sophisticated webapps is probably the most widespread example of an overlay OS today.

What can someone do with Synchronicity? Some examples:

• Listen to a podcast streaming from your phone to your car stereo while driving. When you get to your destination and get out of the car, you can pick up where you left off from your Synchronicity instance on your laptop.
• Start reading a PDF on your desktop computer, then head out to get on public transit, and pick up where you left off on your phone.
• Keep a music library on an always-on cloud server, and stream arbitrary songs to the music player built into your Synchronicity instance.
• Host a code version control system forge like Forgejo or Github.
• Proxy requests to a commercial AI service like Anthropic's Claude or OpenAI's ChatGPT; or run a local Large Language Model and manage chat conversations with it from any device.

Installation and Usage

Note: Synchronicity is actively in development and is an early-stage project. The bulk of its ambitions are yet-unrealized.

A synchronicity node can currently be instantiated as an Android app, a desktop GUI program (only tested on Linux thus far), or a daemon and a CLI tool that interacts with the daemon.

The best way to run the CLI or GUI is to clone this Git repository and build from source, which requires the Rust toolchain. Install the rustup tool according to the Rust official docs, then run rustup toolchain install stable to install the latest stable version of the Rust build tool cargo.

The specific build commands are encoded in the project's justfile.

To compile and run the CLI, run:

$ just cli -s <store-path>

To compile and run the GUI, run:

$ just gui -s <store-path>

<store-path> should be a path to a non-existent directory somewhere convenient on your file system, that will serve as the node store on a PC system. Synchronicity will create the node store directory and populate it with necessary files on first launch.

The node store contains all the data that defines a Synchronicity instance. Only one instance of synchronicity should run using the same node store at the same time. Running two or more instances of synchronicity on the same physical machine with different node stores, looks identical to running those same nodes on different hardware.

The Android build can be compiled with an appropriate Android toolchain and loaded onto a real Android device or emulator; but the easiest way to install it is to use one of the debug build APK packages that are built by CI. You can directly sideload this APK onto an Android phone; or you can use an alternative app store such as Obtanium to install and update APKs directly from the release URL. With Obtanium specifically, use https://code.everydayimshuflin.com/greg/synchronicity as the source URL, and make sure to set the Override source to "Forgejo (Codeberg)", and set the "Include preleases" option.

Initializing an ensemble

Once you have one or more instances of synchronicity running, you will need to set an ensemble key. Your ensemble key is a private key, represented as a sequence of randomly-generated English words, that defines the ensemble of nodes controlled by a single human user. An example ensemble key is silk-impotent radiation-frustrate parkway-entrap imitate-icy (do not use this public example key yourself). It is analogous to the BIP39 keyphrase of a Bitcoin wallet, although using a different format. Keep it secure and secret, and consider storing it in a password manager or other secure secret storage method.

Upon starting up a new GUI or Android node, the welcome screen will invite you to either generate a new ensemble key or to initialize a node with an existing ensemble key. The first time you run a Synchronicity node, generate an ensemble key and then immediately use it to initialize a node. For any additional nodes you initialize, input that same ensemble key directly. The only time you will need to have access to the ensemble key is when you initialize a new node, or (rarely) perform global node-related management like marking a specific node you don't have access to as compromised.

Once you've initialized a node, the node will generate a node-specific public-private keypair that never leaves the node hardware; this key encrypts and decrypts traffic to/from all other nodes in the ensemble. You can look at the "Ensemble" screen to see information about all nodes that your node can reach (note that this functionality is not currently well-tested; there are likely node reachability bugs).

Usage

A lot of functionality is not implemented yet, but there's a few things working that you can play around with. Try navigating to the Documents screen and importing files from your local machine into Synchronicity - static images, PDFs, and music or audio files are good things to try importing and then viewing. Or try using the Podcast screen to search for and listen to a podcast.

Project Structure

Here's a brief overview of the project files in this repo:

• android/ - Android application code, mostly in Kotlin
• rust/ - A Rust-language workspace containing several Rust crates:
  • rust/cli-app - the CLI frontend
  • rust/gui-app - the GUI frontend. This is currently written using the Slint GUI library
  • rust/syn-daemon - common code for the daemon component of the CLI and GUI
  • rust/tui-app - TUI code; not much has been implemented here yet
  • rust/lib - Common code imported by the CLI, GUI, and Android. The bulk of Synchronicity's functionality lives here
  • uniffi-bindgen - auto-generated Kotlin/Rust binding code, via uniffi-rs
  • rust/Cargo.toml - the workspace Cargo.toml file for the entire project. Contains the bulk of the common dependencies.
• docs/ - Design documents, some of which are out-of-date
• scripts - a few basic build and CI scripts
• assets - the program icon, and other assorted program assets

Inspirations and Prior Art

• copyparty
• Urbit - coined the term "Overlay OS" as far as I know