# Island-mode server (Agent Skill)

> An on-premise fallback server: a live replica of your site's cloud data, LAN takeover when the internet drops, and a safe flush of offline work when it returns.

Page: https://timerise.ai/skills/island-mode-server

Agent Skill `island-mode-server`: https://github.com/timerise-ai/island-mode-server. Category: In-venue. Runs on Node.js; backend: Firestore cloud, RxDB on the local box.

Latest release: v0.1.11 (2026-09-29).

Install: npx skills add timerise-ai/island-mode-server. Timerise builds it on a brief; the price comes from the brief.

A shop, gym or clinic cannot stop when the internet drops. The cloud system is unreachable, but customers are at the counter, stock is moving and doors need to open.

This skill builds a small server that runs at the site and keeps a live copy of the site's data. While the connection is up it stays invisible. When the connection drops, kiosks and staff terminals on the local network switch to it. The site keeps taking bookings, moving stock and opening doors. When the connection returns, the offline work flushes back to the cloud exactly once.

Node on the local box, Firestore in the cloud. Hardware authenticates with HMAC. The on-site operations (systemd, nginx) are written down.

Build an on-premise fallback server that keeps a live two-way RxDB replica of a site's slice of Firestore, takes over serving LAN terminals when the cloud is unreachable, and flushes offline work back on reconnect. Use when: (1) a physical site (store, gym, clinic, warehouse) must keep taking bookings, moving stock and toggling hardware through an internet outage, (2) kiosk or staff PWAs must switch between a cloud API and a local API on their own, (3) an existing offline server needs auditing: a reconnect flush that double-counts stock, a replica that stops pulling, a failover that never finds the box, (4) the user mentions: island mode, offline fallback server, LAN failover, on-prem replica, local server with two-way sync to Firestore, "the site keeps working when the internet is down", replicateFirestore, rxdb/plugins/replication-firestore, serverTimestamp checkpoint, _offlineCreated, _locallyModified, syncedIds, FieldValue.increment, heartbeat cron, apiBaseUrl, HMAC device auth, island.local, avahi. Carries the three replication tiers, the checkpoint stamp every cloud write needs, the per-ID stock-delta fold-out, idempotent ingestion keyed on client-generated IDs, the offline-gated staff token fallback, the heartbeat and status chain, and a 17-test vitest suite for the trust-critical logic. Node/NestJS local server and Firestore cloud with Next.js route handlers as the reference API; the HTTP framework, IdP and vocabulary are seams in architecture.md. Not a read cache, not multi-master sync between sites, and not for a cloud database other than Firestore.

The skill was written by the engineers who have shipped this module; the earlier implementation it was audited against was the on-premise fallback of a multi-location venue booking system. The templates hold four properties: a live replica that takes over the LAN when the internet drops, a reconnect flush the cloud can apply any number of times with one result, hardware calls that are HMAC-verified with a replay window, and offline staff tokens that expire. The vitest suite in `assets/` verifies the trust-critical logic, and [`references/provenance.md`](references/provenance.md) is the record of what the audit changed, what was kept and what is new.

What it builds:
- Live RxDB replica of a site's Firestore slice
- LAN takeover when the internet drops
- Idempotent reconnect flush
- HMAC hardware auth

When to use:
- A site must survive internet outages with real writes (bookings, stock, hardware control), not just cached reads.
- Terminals are browser-based (PWA or kiosk) and must fail over transparently.
- Firestore is the cloud source of truth and stays that way.

When not to use:
- Pure read caching, or a PWA that only needs Firestore's built-in offline persistence: the Firebase SDK already does that, with no server.
- A different cloud database (Supabase, Postgres): the replication tier concept travels, but every template here is Firestore-specific.
- Multi-master sync between peer sites: this design is strictly hub-and-spoke, with the cloud as source of truth and last-write-wins conflicts.

Non-negotiables:
- Never expose the cloud sync-ingestion endpoints without auth. They apply stock increments and inject orders, so they are reachable only with a shared-secret header at the minimum; the reference route handlers check it before touching Firestore.
- Never verify offline staff tokens leniently while online. Decoding without verification is an accepted LAN-only trade-off, so it is gated on the server actually being offline; the suite's offline token tests cover the gate.
- Never reset local stock deltas for transactions not acknowledged as synced. Deltas are folded out per transaction ID on acknowledgment, so `effectiveStock` stays correct across a partial flush; the suite's delta fold-out tests run against a real RxDB instance.
- Never let the local server invent business rules the cloud owns (opening hours, pricing). The local server replicates the config and computes from it, so island-mode behaviour matches the website.

Not this:
- Cached reads, or a PWA that only needs offline persistence: The Firebase SDK's built-in offline mode, no server needed
- Supabase, Postgres or another cloud database: The tier concept travels; every template here is Firestore-specific
- Multi-master sync between peer sites: This design is strictly hub-and-spoke, cloud as source of truth
- The kiosk terminal itself: The sibling [`booking-kiosk`](https://github.com/timerise-ai/booking-kiosk) skill, which defines the client-side failover contract against this server

Booking features we build with it:
- Works when the internet fails: /features/offline-mode

What to tell your agent:
- Our climbing gym's front desk must keep taking bookings when the internet drops. Build a local server that replicates our Firestore data, takes over the LAN, and syncs back when the connection returns.
- Our kiosks run in the browser. Make them switch to the local box on their own when the cloud is unreachable, without staff doing anything.

Agent eval results (newest per agent and prompt):
- Gemini CLI (gemini-3.8-flash) on v0.1.11, 2026-09-29: pass (Firestore + RxDB)
- Claude Code (claude-opus-5-5) on v0.1.11, 2026-09-29: pass (Firestore + RxDB)
- Codex CLI (gpt-6-astra) on v0.1.10, 2026-09-29: pass (Firestore + RxDB)

Recent releases:
- v0.1.11 (2026-09-29): From scoring the prompt-1 agent eval runs against 0.1.10.
- v0.1.10 (2026-09-29): Fix release, from scoring the prompt-1 agent eval runs against 0.1.9.
- v0.1.9 (2026-09-29): Fix release, from scoring the prompt-1 agent eval runs against 0.1.8.