Network architecture — settings — Claude on WholeTech

01 — Why bother

The shape decides everything else

A two-machine setup doesn't really have an architecture. By the time you have a laptop, a desk PC, a droplet, a NAS, an iPad, a phone, and a cloud agent, you do — whether you chose one or it grew organically. Picking the shape on purpose decides who's the source of truth, where work flows, what fails-soft when a machine dies, and which machine you spend Sunday evenings debugging.

The choice isn't "more sophisticated is better." A two-PC setup with a primary-and-secondary architecture beats a five-machine mesh whose owner can't explain it. Pick the simplest pattern that handles your real workloads.

The three questions architecture answers: (1) When a thing goes wrong, where do I look first? (2) When I add a new machine, what does it need to know? (3) When I change a setting, where do the others learn about it? If you can answer those three in one sentence each, your architecture is real.

02 — The four

Four patterns, at a glance

Pattern	One-liner	Best at	Worst at
Primary + secondaries	One PC writes the truth; the others mirror it.	Solo operators, 2–5 machines	If primary dies, work pauses
Mesh	Every machine writes; they reconcile.	Teams who can't agree on a primary	Conflicts, drift, "who wrote that?"
Hub-and-spoke	A central store (NAS, droplet) is truth; machines read/write through it.	Many machines, central audit, NAS-backed	Hub becomes single point of failure
Cloud-as-hub	claude.ai threads are the persistent layer; local Claudes are clients.	Threads/Projects-centric work, mobile-heavy	Local CLI sessions aren't part of it

Most real fleets end up hybrid — see §8. The four patterns above are the components you compose from.

03 — Pattern 1

Primary + secondaries

[PRIMARY] your daily-driver PC | writes ~/.claude/ → git +-------+-------+ v v v [secondary] [secondary] [secondary] pull-only; no local divergence

How it works

Pick one machine as the primary. All authored changes (new commands, hooks, MCP servers, edits to settings.json) happen there. The primary commits and pushes ~/.claude/ to a git repo. Every other machine runs git pull --ff-only on a schedule. Secondaries never push; they receive.

Truth lives atThe primary's ~/.claude/

ConflictsDon't exist (only one writer)

FailoverPromote any secondary by editing one config flag

LatencyMinutes (next scheduled pull)

When this is right

Solo operator with 2–5 machines.
You're at the same one of those machines most days — there's a natural "primary."
You don't change settings on the road. The secondaries are passive consumers.

When it's wrong

You routinely make edits on whichever machine you're sitting at. (Mesh is closer to your reality.)
The "primary" travels with you and is often offline. Secondaries stall while waiting.
Multiple humans share machines. There's no single primary.

The five-minute setup

Pick the primary. Make ~/.claude/ a git repo. Push to a private GitHub repo.
On each secondary, back up the existing ~/.claude/, then clone the repo over it. Re-run claude login on each.
Add a scheduled task on each secondary: nightly git -C ~/.claude pull --ff-only.
Pin a habit: on the primary, after any settings change, git add && commit && push. Resist the urge to edit on a secondary.

Recovery story: primary dies → SSH/RDP into any secondary → git -C ~/.claude push origin HEAD:main --force from there (since secondaries already have the latest pulled state) → promote it to primary in your head. Down-time: ten minutes if the secondary is already running.

04 — Pattern 2

Mesh

[A] <----> [B] \ / \ / [C] every node writes & pulls OneDrive / Dropbox / Syncthing handles propagation

How it works

No primary. Every machine can edit ~/.claude/; a live-sync service (OneDrive, Dropbox, Syncthing, iCloud Drive) propagates changes between them. Conflicts are detected by the sync layer and surfaced as "conflicted copy" files for human resolution.

Truth lives atWherever the most recent edit happened

ConflictsCommon; sync layer's problem

FailoverAny machine surviving is the primary

LatencySeconds (live sync)

When this is right

Two or three machines, all owned by the same person, all online most of the time.
You're as likely to make a settings change on the laptop as on the desk PC. No natural primary.
The fast feedback (live propagation) matters more than the cost of occasional conflicts.

When it's wrong

More than three machines. Conflict surface grows fast.
Sensitive secrets shouldn't be in Dropbox/OneDrive (they shouldn't be in git either — but a synced folder is browseable by support staff in ways a private repo isn't).
Anything with auth.json. Two simultaneous logins on different machines create two valid auth tokens; sync can race and one wins; the other Claude gets logged out. Always gitignore/exclude auth.json from the sync set.

The "selective mesh" trick

Don't sync the whole ~/.claude/ tree; sync only the parts that don't cause conflicts. The auto-memory directory is the strong candidate (small text files, lineable diffs). commands/ and skills/ too. Keep settings.json in git instead — that's where the JSON conflicts hurt.

Mesh-and-JSON is bad day: two machines saving settings.json within seconds of each other reliably produces a "conflicted copy" that Claude doesn't read. You'll wonder why your new hook isn't firing. Use git for JSON; use a sync folder for directories.

05 — Pattern 3

Hub-and-spoke

[laptop] [desk PC] [mac] \ | / \ | / \ | / [HUB — NAS / droplet] single source of truth for config, queue, logs / | \ v v v [droplet] [backup] [CC NAS] downstream consumers

How it works

A central host — a NAS, the droplet, a small VPS — holds the canonical ~/.claude/. Machines mount it (SMB, NFS, SFTP) or pull from it on a schedule. The hub also typically holds the shared task queue (see /settings/communication §3), the fleet log, and the notification routing config.

Truth lives atThe hub

ConflictsHub mediates; first-writer wins

FailoverHub down → whole fleet degraded

LatencyPer-fetch (depends on transport)

When this is right

Five or more machines. The "every machine talks to every other machine" approach stops scaling.
You already have a NAS or a droplet that's always on.
Central audit matters — compliance, security review, "what did each Claude do last week."

When it's wrong

You don't have a hub-class machine. Spinning one up only for this is overkill for a small fleet.
The hub's network is unreliable. Your laptop on a plane can't read settings if the hub is the source of truth.
Lots of small, frequent edits. Hub I/O becomes the bottleneck.

The "hybrid hub" pattern

Don't put everything on the hub. Local ~/.claude/ is each machine's fast path; the hub holds the slow-path canonical version that nightly syncs reconcile against. Best of both worlds — local responsiveness, central truth.

06 — Pattern 4

Cloud-as-hub

[claude.ai] threads · projects · agents ^ ^ ^ custom instructions | | | +----+ +----+ | | [web] [managed agent] parallel cloud workers [iOS] [Android] mobile clients [Code CLI] [droplet] local Claudes — independent; not part of the cloud hub

How it works

Recognise that claude.ai already is a hub for the cloud-side surfaces. Threads, Projects, Project files, custom instructions, managed agents — they all live in your Anthropic account. The web, iOS, and Android clients are thin views over the same state. The local Claudes (CLI, your droplet) sit alongside this hub but aren't part of it — they're separate networks that talk to you, not to each other through the cloud.

Truth lives atclaude.ai (your Anthropic account)

ConflictsLast-write-wins via Anthropic's storage

FailoverAnthropic's problem

LatencySeconds (real-time sync)

When this is right

Your work is mostly conversational, not local-filesystem-heavy. Research, writing, planning, drafts.
You operate across web + phone + tablet daily, and the threads need to flow.
You don't have or want a self-hosted hub.

When it's wrong

Your work is mostly via Claude Code on the desktop. Those sessions don't show up in claude.ai threads.
You need offline access to the truth. The cloud-as-hub is a cloud-dependent design.
You need audit logs richer than what claude.ai surfaces.

The "two halves" reality

Most real fleets run cloud-as-hub for the conversational half (web, mobile, projects, managed agents) and primary-or-hub-and-spoke for the local-tooling half (Claude Code, MCP servers, queue workers). They're separate networks with separate truths. Don't try to merge them; let each be what it is.

07 — Decision matrix

Picking yours

If…	Pattern
2–3 machines, one is clearly your daily	Primary + secondaries
2–3 machines, no clear primary, all online most of the time	Mesh (selective)
5+ machines, central NAS or VPS already running	Hub-and-spoke
Lots of mobile/web work, Code CLI is a secondary tool	Cloud-as-hub for conversational; small primary for CLI
Compliance / audit requirement	Hub-and-spoke (single audit point)
Team of humans on shared boxes	Hub-and-spoke, hub-managed permissions
Solo, occasional Mac/Linux machine	Primary + secondaries; secondaries pull on use, not on schedule

The three questions you must answer

Who writes? One machine, every machine, the hub, or the cloud?
How do others learn? Git pull, live sync, hub read, cloud sync?
What breaks when the source dies? If you can't answer, your architecture has a hole.

08 — Mixing

The real world is hybrid

Pure patterns are rare. Most working fleets compose two or three. The trick is being deliberate about which pattern handles which surface — not letting them tangle.

The three working hybrids

solo + cloud

Solo dev with mobile habits

Primary + secondaries for local CLI / desktop machines; cloud-as-hub for conversational work on web + iOS + Android. Two trees that don't try to merge.

team + hub

Small team with shared infra

Hub-and-spoke for shared config (in a private GitHub repo + a NAS mount for the queue); cloud-as-hub layered on for everyone's personal threads.

mesh + queue

Power user with three PCs

Selective mesh (OneDrive for memory + commands; git for settings.json) plus a tiny hub-style queue on the NAS for asynchronous overnight work.

The rule that keeps hybrids sane

Each surface has one home pattern. Settings live in one place. Memory lives in one place. Skills live in one place. Two patterns may both touch the same machine, but they don't both claim ownership of the same file. Write down (in ~/.claude/CLAUDE.md) which pattern owns which surface.

09 — Worked example

The WholeTech architecture

Concrete. Two Windows PCs (CC and HS), a Linux droplet, two NAS boxes, an iPhone or Android, and managed agents in the cloud. Here's how those fit together as a hybrid of three patterns.

Pattern composition

Local config — primary + secondaries. CC PC is primary; HS PC and the droplet are secondaries. ~/.claude/ lives in a private GitHub repo. Nightly git pull on the secondaries.
Backups + queue — hub-and-spoke. The HS NAS and CC NAS hold the canonical websites/ tree; the droplet is the deploy target; rclone fans content to B2 and Google Drive on a nightly schedule. Six legs as described in /settings §5.
Conversational — cloud-as-hub. iOS, Android, and the web client share threads through claude.ai. Managed agents kick off from the web or from GitHub mentions.

Who talks to whom

From	To	Via	What
CC PC	HS PC	git push / pull	Config updates
CC PC	droplet	ssh + scp	Site deploys, remote Claude invocations
droplet	CC NAS / HS NAS	pull-model rclone	Nightly backup mirror
CC PC	B2 + Drive	rclone push	Nightly off-site backup
iOS / Android	claude.ai	HTTPS	Threads, voice, camera, share-sheet
CC PC	claude.ai	HTTPS	Managed agent kick-offs; web threads
droplet cron	CC PC + phone	ntfy push	Notifications (sitemap rebuild, cert renewal)

What dies cleanly

CC PC dies → promote HS PC by pulling latest and pushing to GitHub from there; mobile and web keep working through cloud-as-hub. Droplet dies → sites go down; deploy from CC PC is paused; local config and backups untouched. NAS dies → queue and historical backups paused; rebuild from B2 or Drive. claude.ai down → mobile and managed agents pause; local Claude Code keeps working.

10 — Scaling

Beyond five machines

Architecture choices that work for three machines start straining at six and break at twelve. The trip-wires:

Where each pattern starts to hurt

Pattern	Breaks at roughly	Why
Primary + secondaries	~8 machines	Single primary becomes a bottleneck on changes; failover needs more thought.
Mesh	~4 machines	Conflicts grow O(n²); auth.json races; sync layers struggle.
Hub-and-spoke	~50+ machines	Real scaling story; can support a small team for years.
Cloud-as-hub	n/a	Anthropic scales it; you don't.

The "tier" structure for >10 machines

Group machines into tiers:

Tier 1 — Authors. 1–3 machines where you actually make changes.
Tier 2 — Workers. Machines that run scheduled / queued / remote-invoked Claude work; receive config but don't author.
Tier 3 — Endpoints. Phones, tablets, throwaway VMs. Read-mostly; recreated easily.

Tier 1 is primary-and-secondaries internally; tier 2 reads from the hub; tier 3 is cloud-as-hub. Three patterns, one fleet, each surface has one home.

11 — Bottlenecks

Where the real slowness lives

In a multi-machine fleet, perceived performance has less to do with any single Claude's speed and more to do with where the joints are. Five common ones:

network

SSH round-trip from a hotel

Remote invocation feels great at home and brutal at 200ms latency. Pre-pull state, batch commands, prefer the queue pattern over per-keystroke ssh.

git

Pulling a large sessions/ folder

You forgot to gitignore sessions/ and the repo is now 800 MB. Every pull on every secondary is a minute. Fix the .gitignore, git filter-repo to purge history.

mcp

Cold-start of MCP subprocesses

Each fresh Claude session spawns its MCP servers. If you have ten of them and they each npx -y, that's a slow first prompt. Switch heavy ones to long-running HTTP/SSE.

queue

Worker polling interval

Workers sleeping 30 seconds between scans = up to 30s of latency for "kick off a task." Trade off: shorter sleeps = more idle CPU. Pick 5s for active fleets.

cloud

Anthropic rate limits

Five managed agents in parallel can hit the per-account TPM cap. Stagger kick-offs, or split into separate accounts if you're really doing this.

human

You

The biggest bottleneck. If three Claudes all need decisions from you and you're at lunch, the fleet is paused regardless of architecture. Design for fewer interrupts.

12 — Migration

Moving between patterns

Most fleets evolve. You started solo with two PCs; now you have five and a droplet; soon you'll have a teammate. Migrations are doable but they punish you for not thinking through "where does the truth live."

Mesh → Primary + secondaries

Pick the primary. The machine where most changes happen. (Use git log --pretty=format:%cn ~/.claude/ | sort | uniq -c if the repo's already shared.)
Stop the live-sync from touching ~/.claude/ on all machines. Move the synced contents to a separate ~/.claude.sync/ for now.
Initialise ~/.claude/ as a git repo on the primary. Push.
On secondaries: clone the repo over ~/.claude/. Cherry-pick from ~/.claude.sync/ anything that didn't make it to the primary.
Add scheduled pulls; remove the live-sync rule entirely.

Primary + secondaries → Hub-and-spoke

Stand up the hub. NAS share or droplet directory with the same layout as ~/.claude/.
Sync the primary's ~/.claude/ to the hub. Make the hub the new git remote.
Secondaries now pull from the hub instead of GitHub. Faster if local; same protocol.
Move queue + logs + notification routing to the hub if they weren't already.

Anything → Cloud-as-hub (for the conversational half)

This isn't a migration so much as a recognition. The cloud-as-hub already exists for your claude.ai-family work whether you set it up or not. Just use it intentionally: web threads as the persistent layer; mobile and managed agents as collaborators.

The one migration rule: never run a half-migrated fleet for more than a day. Two patterns racing for ownership of the same surface produces confused state that's much worse than either pattern alone.

13 — Pitfalls

What goes wrong

drift

The "I'll just edit it here" creep

Single-primary discipline breaks down the moment you fix a typo on a secondary "just this once." Three weeks later the primary doesn't have the fix. Force yourself: always commit on the primary; if the primary's not handy, write a sticky note.

orphan

The machine nobody manages

That spare laptop, the third Mac mini, the old desktop in the basement — they receive config updates but nobody verifies them. They drift silently and surprise you when needed. Audit the fleet quarterly.

over-engineer

The hub-and-spoke for three machines

Standing up a NAS share and a queue and a fleet log for a setup that's two PCs and a droplet is over-engineering. Start with primary + secondaries; promote to hub-and-spoke only when it's needed.

silent

The pull that never fired

Secondary's scheduled task disabled itself six weeks ago after a failed run. You've been working off stale config. Add a heartbeat: secondary writes $(date) to a fleet-wide log after every successful pull.

split

Cloud and local thinking they're one fleet

They aren't. Don't try to make web threads sync to your CLI history or vice versa. Two networks, different jobs.

key

One SSH key everywhere

The temptation to use the same SSH keypair on every machine because "it's easier." It isn't — it makes a stolen laptop a fleet-wide compromise. One key per machine, always.

14 — Related

The rest of the hub

/settingsthe hub /communicationinter-Claude primitives /os-matrixWindows · macOS · Linux · WSL /terminalsshells & terminals /recoverydisaster recovery /skillsworkflows to bundle /computersthe WholeTech machine inventory

Network architecture for a Claude fleet

The shape decides everything else

Four patterns, at a glance

Primary + secondaries

How it works

When this is right

When it's wrong

The five-minute setup

Mesh

How it works

When this is right

When it's wrong

The "selective mesh" trick

Hub-and-spoke

How it works

When this is right

When it's wrong

The "hybrid hub" pattern

Cloud-as-hub

How it works

When this is right

When it's wrong

The "two halves" reality

Picking yours

The three questions you must answer

The real world is hybrid

The three working hybrids

Solo dev with mobile habits

Small team with shared infra

Power user with three PCs

The rule that keeps hybrids sane

The WholeTech architecture

Pattern composition

Who talks to whom

What dies cleanly

Beyond five machines

Where each pattern starts to hurt

The "tier" structure for >10 machines

Where the real slowness lives

SSH round-trip from a hotel

Pulling a large sessions/ folder

Cold-start of MCP subprocesses

Worker polling interval

Anthropic rate limits

You

Moving between patterns

Mesh → Primary + secondaries

Primary + secondaries → Hub-and-spoke

Anything → Cloud-as-hub (for the conversational half)

What goes wrong

The "I'll just edit it here" creep

The machine nobody manages

The hub-and-spoke for three machines

The pull that never fired

Cloud and local thinking they're one fleet

One SSH key everywhere

The rest of the hub