Multi-PC Sync

Agenties stores all project state locally, but your issues, team, and configuration are continuously synced to the Agenties cloud backend. Any machine running Agenties with your account can pick up where you left off — issues are current, team XP is up to date, and config changes propagate in about a second.

What gets synced

File	Syncs?	Debounce	Notes
`issues.json`	Yes	1 second	All issue fields including status, priority, description, and labels
`team.json`	Yes	1 second	Team roster, XP, stats. linkedAgentId is excluded (machine-local)
`config.json`	Yes	3 seconds	Heartbeats, routines, toolPermissions, sync settings
`shared/state.json`	No	—	Local ephemeral state — orchestrator session IDs, active agents
`mailbox.jsonl`	No	—	Local message bus — delivery is machine-specific

Note:The vault (Obsidian files) is not synced through Agenties — use Obsidian's own sync or a cloud storage solution (iCloud, Dropbox, OneDrive) to sync your vault across machines.

Sync architecture

Agenties cloud backend

The Agenties cloud backend stores the canonical copy of synced data. Each project has a unique project ID that links the local .agenties/ directory to its cloud counterpart. You connect using the same account you use for agenties.app — no additional credentials required.

Real-time sync

Agenties maintains a persistent real-time connection for each open project. Changes flow through a dedicated channel per project and use an inline datapattern — the payload always contains the full data array rather than a diff. This eliminates the classic race condition where an event says "data changed" but the follow-up fetch returns stale data. When you receive an event, you already have the latest data.

Push and pull behaviour

Push (local → cloud)

Every time a local state file changes, Agenties queues a push with a debounce timer:

Push debounce

issues.json  → debounce 1000ms → push to cloud
team.json    → debounce 1000ms → push to cloud
config.json  → debounce 3000ms → push to cloud

Rapid local changes (e.g. the orchestrator updating 5 issues in quick succession) are batched into a single push at the end of the debounce window.

Pull (cloud → local)

Pull from the backend only happens in two situations:

Local file is missing or emptyOn project open, if issues.json or team.json is absent (e.g. new machine), Agenties pulls from the cloud backend to seed the local file.

Real-time event from another deviceWhen a sync event arrives from a different device, the inline data is written to the local file immediately.

Warning:Agenties does not do three-way merge for conflicting concurrent edits on the same issue. The last write wins. If two people edit the same issue simultaneously on different machines, one change will be overwritten. This is a known limitation — conflict resolution is on the roadmap.

Setting up a new machine

To access your projects on a second machine:

1.Install Agenties on the new machine (npm install -g agenties).

2.Sign in with the same account.

3.In the Projects panel, your existing projects appear in the list (fetched from the cloud backend).

4.Click a project → "Open locally". Agenties prompts you to choose a local folder for the project files.

5.It creates a .agenties/ directory, pulls team.json, issues.json, and config.json from the cloud, and opens the project.

6.The vault is not set up automatically — configure the vault path in Settings → Memory.

Sync status indicator

The Agenties status bar shows a sync indicator in the bottom-right corner:

Indicator	Meaning
Green dot	Connected and in sync
Pulsing dot	Push in progress (debounce window active)
Yellow dot	Reconnecting
Red dot	Offline — changes are queued locally and will sync on reconnect

Tip:You can force a manual sync at any time from Settings → Sync → Push now / Pull now. This is useful after resolving a conflict or if you suspect the local state is stale.

← PreviousVoice Chat Next →Permissions