mcuemcuedocs
Sign in to HubRequest alpha access

Work offline and sync

Offline is the normal case, not the error case. mcue applies your work locally first and treats the network as something that eventually confirms it — so losing connectivity costs you nothing but confirmation.

What happens when you are offline

A local mutation:

  1. is validated and applied locally, immediately,
  2. is written to a durable outbox,
  3. stays visibly pending until Hub accepts it.

You keep working. Nothing blocks on the network, and nothing is queued in memory where a crash would lose it — the outbox survives restarts.

Seeing what is pending

mcue sync status payments-api

This makes no network request. It reads your cursor and outbox and reports what has not been accepted yet. Run it before you get on a plane and after you land; it is the honest answer to "did that go through?"

Across every project at once:

mcue hub status

Reconnecting

mcue sync payments-api

On reconnect mcue exchanges pending operations and pulls accepted events after your cursor, then rebuilds the accepted base and replays anything still pending on top.

Push and pull are one command because doing them separately is how replicas get subtly wrong. Sync several projects, or all of them:

mcue sync payments-api ledger-svc
mcue sync --all

The scenario worth understanding

Two machines, both offline, both writing to the same lane. This is the case distributed systems usually handle badly.

  • Both wrote checkpoints. Checkpoints are append-only. Both survive. The lane becomes divergent and needs mcue reconcile payments-api — a human decision about which perspective is right.
  • One wrote against stale mutable state. That write is rejected with the current revision and a typed conflict. It is not silently overwritten, and it is not silently dropped from your outbox.
  • A response was lost in flight. Retrying is safe. Every operation carries an operation_id; replaying it returns the original result rather than appending a duplicate.

The rule underneath all three: mcue never resolves a disagreement about what happened by comparing clocks. See Authority and conflicts.

The eight-hour test

The scenario Hub exists to pass:

  1. Publish a project from your laptop.
  2. Connect an MCP client to the hosted endpoint and confirm read and write access.
  3. Shut the laptop down completely. No tunnel, no daemon left running anywhere.
  4. Hours later, resume the project and write a closeout through the hosted endpoint.
  5. Start the laptop and run mcue sync.
  6. The hosted write appears locally with the right actor, device, substrate, and ordering.

If that fails, Hub is not doing its job. It is the acceptance test the whole hosted side is built around.

BYO-S3, without Hub

If you want cross-machine sync without a hosted service, the mcue remote namespace syncs perspectives through an S3-compatible bucket you control:

mcue remote enable payments-api
mcue remote push payments-api
mcue remote pull payments-api
mcue remote status payments-api

This is a separate path, part of the Apache-2.0 CLI — it is not renamed Hub commands, and it does not require an account. It gives you machine-to-machine sync but not a persistent endpoint that answers while every machine is off.

If a sync looks wrong

  • mcue sync status <project> first — it is offline and tells you the actual cursor.
  • mcue hub status to confirm you are pointed at the Hub you think you are.
  • mcue whoami to confirm the session is still valid.
  • mcue doctor if the binary or $MCUE_HOME itself is in question.