Skip to main content

​
Local Sync

The feature that makes Hubify sticky. Your local environment and your cloud workspace share the same brain — memory, learnings, skills, and context flow between them automatically. Work in your IDE locally during the day. Your cloud agent works overnight. When you open your laptop in the morning, everything is synced. No manual copy-paste. No stale context.
Sync is currently polling-based (every 30 seconds) with last-write-wins semantics. Files created locally are pushed to Convex; files created in the cloud are pulled to your local memory directory. Real-time WebSocket sync and automatic conflict resolution are planned for a future update.

​
Why Sync?

Without SyncWith Sync
Cloud agent and local agent have separate memoryOne shared memory store via Convex
Skills installed locally are unknown to your cloud workspaceSkill manifest synced across both
Learnings captured overnight are stuck in the cloudLearnings pulled to your local learnings/ directory
You brief your agent twice (once locally, once in the cloud)Brief once, context propagates everywhere

​
Prerequisites

Before running sync, you need:
  1. Hubify CLI installed — see Installation
  2. Authenticated — run hubify auth login
  3. HUB.yaml in your workspace — run hubify init to create one, or have one from a template

​
Setup

1

Authenticate

Log in to Hubify from your terminal:
hubify auth login
This stores your credentials locally for CLI operations.
2

Connect to your hub

Navigate to your workspace directory (where HUB.yaml lives) and run:
hubify connect
The CLI reads your HUB.yaml, auto-detects your platform, registers your local machine as an agent in your hub, and performs an initial sync.
3

Start the sync loop

To keep sync running in the background:
hubify connect --watch
This watches your local memory directory for changes and syncs every 30 seconds.

​
What Syncs

SyncedDetails
Memory filesAll .md files in memory/ (daily logs, intel files, state files)
SOUL.mdAgent identity and personality
MEMORY.mdLong-term curated memory
AGENTS.mdAgent instructions
Skills manifestWhich skills are installed and their versions
LearningsStructured learnings extracted by agents

​
What Does Not Sync

Not SyncedWhy
Raw project filesYour codebase stays local — sync is for agent context, not source code
Local shell environmentEnvironment variables, PATH, shell history are machine-specific
Platform-specific configs.cursor/, .vscode/, .claude/ stay on their respective machines

​
Sync Frequency

The sync loop runs every 30 seconds in the background. When --watch mode is active, file system events also trigger immediate pushes — so changes to memory files are pushed within seconds.
DirectionTriggerFrequency
Local to CloudFile change detected by fs.watchImmediate
Local to CloudPeriodic sweepEvery 30 seconds
Cloud to LocalPeriodic pullEvery 30 seconds

​
How hubify connect Works Internally

Here is what happens when you run hubify connect:
1

Find HUB.yaml

The CLI walks up the directory tree from your current working directory, looking for a HUB.yaml file. It stops at your home directory. If no HUB.yaml is found, it prompts you to run hubify init or pass --hub-id directly.
2

Read OpenClaw config

The CLI checks for OpenClaw configuration files to get your user identity. It searches these paths in order:
  • $OPENCLAW_CONFIG (environment variable, if set)
  • ~/.config/openclaw/config.yaml
  • ~/.config/openclaw/openclaw.json
  • ~/Library/Application Support/openclaw/openclaw.json
  • ~/.openclaw/config.json
3

Auto-detect platform

The CLI detects which AI coding platform you are using based on environment variables:
  • CURSOR_DIR or CURSOR_SESSION — Cursor
  • WINDSURF_SESSION — Windsurf
  • CLAUDE_CODE or ANTHROPIC_API_KEY — Claude Code
  • ~/.config/openclaw exists — OpenClaw
  • Otherwise — unknown
4

Generate machine ID

A stable machine identifier is generated from a SHA-256 hash of your hostname combined with your platform name. This ensures the same machine always registers as the same agent.
machine_id = sha256(hostname + "-" + platform).slice(0, 16)
5

Register agent

The CLI calls the hubs.connect Convex mutation, registering your local machine as an agent in your hub. The hub records your platform, machine ID, and agent name.
6

Initial sync

All local memory files are compared against the sync cache by file hash. Changed files are pushed to Convex. Recent cloud memory entries (from other agents) are pulled to your local memory/ directory.
7

Save state

Connection state and sync cache are saved to disk so subsequent runs can resume efficiently.

​
State Files

The CLI stores sync state in your home directory:
FilePurpose
~/.hubify/connect-state.jsonConnection metadata: hub ID, machine ID, platform, timestamps
~/.hubify/sync-cache-{hubId}.jsonPer-hub sync cache: filename, content hash, last sync time for each file
These files enable efficient incremental sync — only files whose content hash has changed since the last sync are pushed.

​
Example Output

A successful hubify connect session looks like this: 
  Hubify Connect -- Local <-> Cloud Sync

  Found HUB.yaml (hub: Houston's OS)
  OpenClaw user: user_abc12345...
  Platform:   claude-code
  Machine ID: 8f3a2b1c9d4e7f01...
  Agent:      houstons-macbook

  Connected to hub: Houston's OS
  Hub URL:    https://houston.hubify.com
  Agents:     2 connected

  Memory dir: /Users/houston/clawd/memory

  Initial sync...

  Pushed: 3 files  |  Pulled: 1 files  |  Unchanged: 12

  Hub connected!

Next steps:
  hubify connect --watch  -- keep running and auto-sync
  hubify status           -- show sync status & connected machines
  hubify connect --once   -- sync once and exit

  State saved to: /Users/houston/.hubify/connect-state.json

​
Troubleshooting

“No hub ID found”The CLI could not find a HUB.yaml in the current directory or any parent directory. Solutions:
  • Run hubify init to create a HUB.yaml
  • Pass the hub ID directly: hubify connect --hub-id <id>
  • Pass the subdomain: hubify connect --subdomain houston
“Cloud registration failed — proceeding in offline mode”The CLI could not reach the Convex backend. This can happen if:
  • You are offline or behind a restrictive firewall
  • The NEXT_PUBLIC_CONVEX_URL environment variable is not set
  • Your Convex deployment is down
The CLI will still sync locally and retry on the next cycle.

​
Next Steps

Connect OpenClaw

Connect an existing OpenClaw instance to Hubify

Cloud Workspace

What runs in your cloud workspace

Agent Memory

How memory works across local and cloud

CLI Reference

Full CLI command reference