Usage & Features

Cloud Sync

On this page

Chain Hub uses Git behind the scenes to securely synchronize your entire instruction library, rule presets, agents, and workflows across multiple devices.

Unlike typical cloud folders (like Dropbox, iCloud, or Syncthing) which can corrupt git history, lock files, or propagate accidental deletions, Chain Hub’s synchronization model is built on standard Git branching and conflict resolution.

How it works

When you initialize sync, the CLI turns your active hub path (~/chain-hub) into a local Git repository and binds it to a private remote repository of your choice.

The Synchronized Architecture:



    

  • Local Repositories: Your hub directory on each machine (e.g. Laptop A and Laptop B) acts as a local Git repository tracking your rules and assets.
    • 

  • Private Central Remote: A central, private repository (hosted on GitHub, GitLab, etc.) securely stores the revision history.
    • 

  • Rebase Integration: Devices synchronize by pushing local updates and pulling/rebasing upstream commits from the remote repository.
    • 



During a sync event:


    

  1. The CLI stages and commits any new or changed assets in your hub.
    2. 

  2. It fetches upstream changes from your remote.
    3. 

  3. It performs a fast-forward merge or rebase to integrate changes from other devices.
    4. 

  4. It pushes your commits to the remote.
    5. 






The easiest way to set up sync is from the local dashboard (chain hub).


    

  1. 

    Open Skills (or the dashboard) and click Sync.
    

    2. 

  2. 

    If your hub is not yet a Git repository, choose Initialize local repository.
    

    3. 

  3. 

    When no remote is configured, click Set up GitHub sync.
    

    4. 

  4. 

    Install the GitHub CLI if prompted, then Sign in with GitHub (opens a browser login via gh auth login --web).
    

    5. 

  5. 

    Choose one of two paths:
    

    Create new repo — for your first machine or a fresh backup:
    

      

    • Enter a repository name (default: chain-hub).
      • 

    • Click Create Chain Hub repo.
      • 

    • Chain Hub creates a private GitHub repository, sets origin, and pushes your hub as the first commit.
      • 

    

    Link existing repo — when you already sync Chain Hub on another device:
    

      

    • Pick your existing repository from the list (likely Chain Hub repos appear first), or paste owner/repo or the full HTTPS/SSH URL.
      • 

    • Click Link Chain Hub repo.
      • 

    • Chain Hub sets origin without overwriting the remote history. Run Sync Now to pull or push.
      • 

    

    6. 

  6. 

    Click Sync Now whenever you want to upload local changes or download updates from other machines.
    

    7. 



 
Another Git host? In the GitHub setup panel, use Use another Git host to paste a remote URL manually (GitLab, self-hosted, etc.). You still need Git credentials configured in your shell for push and pull.
 


After linking on a second machine, run chain setup and chain validate so IDE symlinks and the registry match the pulled hub content.




Get started from the CLI


You can also configure sync entirely from the terminal — useful for scripts, SSH-only workflows, or non-GitHub remotes.


    

  1. Create a private remote repository on GitHub, GitLab, or any Git host (or use an empty repo you already created).
    2. 

  2. Authenticate your environment — SSH keys, gh auth login, or an HTTPS token with push access.
    3. 

  3. Initialize synchronization:
    4. 



  
 
   chain sync init git@github.com:YOU/chain-hub.git  
 
 


    

  1. Run a sync cycle:
    2. 



  
 
   chain sync  
 
 


    

  1. Check status:
    2. 



  
 
   chain sync status  
 
 


chain sync init:


    

  • Runs git init in your hub if needed
    • 

  • Ensures .gitignore for machine-local files (for example brain.db*, .chain/active-project.json)
    • 

  • Sets origin to your URL
    • 





Day-to-day



























ActionHubCLI
Full sync (commit, pull/rebase, push)Sync Now in the Sync modalchain sync
Connection healthSync modal status panelchain sync status
Change remoteEdit remote or re-run GitHub setupgit remote set-url origin <url>


The Sync modal shows whether your branch is clean, ahead, behind, or has local changes. If there is no remote, status will say so explicitly — it will not claim you are “in sync” with a remote that does not exist.




Synchronization Best Practices




[!WARNING]
Do NOT run external file synchronization utilities (like Syncthing, Dropbox, Resilio Sync, or OneDrive) on your active hub directory in parallel with Git sync. Doing so can cause working-tree locks, merge conflicts, and accidental file overrides.




    

  • Private Repositories Only: Your hub contains personal preferences, codebase instructions, and possibly project rules. Always keep your sync repository private.
    • 

  • One sync system: Use either Chain Hub Git sync or a folder sync tool on ~/chain-hub — never both.
    • 

  • Run Setup After Sync: If you pulled down changes that added or updated adapter plugins, run chain setup to update your IDE symlinks.
    • 

  • Sync Configuration: Machine-specific paths (like editor config paths in ~/.config/chain-hub/config.json) are not synchronized; they remain completely local to each device.
    • 





Troubleshooting


GitHub setup says “Install GitHub CLI”


Install gh from cli.github.com, then sign in from the Sync modal or run:


  
 
   gh auth login  
 
 


Create failed because the repository already exists


Switch to Link existing repo in the hub and select that repository, or use the CLI with chain sync init and your existing remote URL.


Private GitHub pack install fails (separate from hub sync)


Hub sync uses gh for repository setup; pack installs accept GITHUB_TOKEN, GH_TOKEN, or gh auth token. See Troubleshooting for pack install details.