Using Pagr

When your Mac is offline

Nothing runs in Pagr's cloud on your behalf. When the Mac is unreachable, work does not happen — but nothing is silently dropped either, and you are always told which of the two you are getting.

What offline means#

The bridge holds one outbound WebSocket to the Pagr gateway and sends a heartbeat every 20 seconds. Your Mac counts as offline the moment that connection drops — asleep, lid closed, off the network, daemon stopped, or behind a proxy that has started interfering.

$pagr statusPagr bridge  device    dev_9c1f4a7… studio  gateway   ! daemon not running  daemon    ✗ not running

Commands you send while it is offline#

Texting still works. The control plane accepts the instruction, queues the signed command, and says so plainly rather than pretending something started:

you   start codex on checkout-api and run the testspagr  studio is offline. I queued that and will start Codex on      checkout-api when it reconnects.

Queue behaviour
Aspect	Behaviour
Lifetime	12 hours by default. A command older than that is never delivered.
On reconnect	Every queued command is re-validated before dispatch — signature, device binding, expiry, nonce and the existence of the project or session it names.
Stops and approvals	Also queued, and they carry tighter deadlines: a stop expires after 15 minutes, and an approval decision expires when its approval does.

Events the bridge could not deliver#

The traffic in the other direction is buffered on your Mac. While disconnected, the bridge holds up to 500 protocol events in memory and flushes them on the next successful authentication. Past that, the oldest are dropped rather than growing without bound.

pagr status shows the buffer depth in its JSON output, so pagr status --json is the quickest way to see whether the daemon has a backlog.

Reconnection#

Reconnection is automatic and needs no intervention. The bridge backs off exponentially from one second to a ceiling of one minute, with up to fifty per cent jitter so a fleet of Macs coming back from a network blip does not arrive in lockstep.

Two conditions stop it retrying:

The bridge is too old. If the gateway advertises a minimum bridge version higher than the one running, the daemon stops reconnecting and logs an update-required error. Fix it with npm i -g @pagr/cli@latest and pagr daemon install.
The device was revoked. See below.

Revoked devices#

Revoking a Mac in the dashboard removes its public key server-side. Its socket is closed and its signatures are refused from that moment on. The daemon logs auth failed and gives up.

Re-pairing mints a brand new identity — revoked key material is never reused:

$pagr logout    # remove the launch agent, delete the private key, drop config$pagr connect   # new key, new dev_… id$pagr projects  # still registered; the cloud learns the ids on the next connect

Your project registry survives a logout. Use pagr logout --purge to drop it too, or pagr uninstall --yes to remove ~/.pagr entirely.