The Firenook blog

How Firenook writes 40× faster than the Firebase emulator

Fri, 23 Oct 2026 00:00:00 GMT

Under a real application’s traffic, Firenook acknowledged a Firestore write in 5.1 ms at the median, where the official emulator took 208.2 ms. This post explains that number from Firenook’s source: what a write does, what it skips, what that costs in durability, and where the comparison stops holding.

What the 40× measures

The number comes from two hours of one application’s traffic against each emulator in turn: two busy sessions writing, open listeners, a filtered query every 15 seconds, a Firestore-triggered function and Storage uploads. The client timed each of the 5,280 writes per emulator, from call to answer.

Median / 99th percentile	Official	Firenook
Write, acknowledged	208.2 / 279.8 ms	5.1 / 50.6 ms
Listener update after a write	209 / 258 ms	11 / 60 ms

It is not the cost of a write on an idle emulator. With each emulator alone, writing a document and deleting it took 3.01 ms on the official emulator and 1.96 ms on Firenook at the median: 1.5×. The 40× is how the two behave under load, so the real question is narrower than the title: why does a Firenook write stay cheap while an application runs around it?

What a write does

A commit enters the disk store through DiskStore::commit_observed in crates/core-store/src/disk.rs. It takes five steps.

Read what it touches. The store reads the documents the commit writes from redb, one key lookup each. It never reads the collection.
Plan. It applies each write to those documents in memory: preconditions, transforms such as server timestamps and increments, and the new revision. The result is a list of changes, each with the document before and after.
Append to the journal. The commit is framed (a magic number, its length and a CRC32C) and appended to a journal file with a plain write. No fsync.
Commit to redb. redb is an embedded key-value store written in Rust, built on copy-on-write B-trees. One write transaction stores the document, its entries in the collection, collection-group and ordered field indexes, and the store’s revision. It commits with redb’s Durability::None, so it does not sync either.
Record and notify. The change goes into an in-memory change log, bounded at 4,096 changes or 64 MiB, and the commit’s observers hear about it. Then the client gets its answer.

The choice in step 4 is one function:

const fn redb_durability(durability: DiskDurability) -> Durability {
    match durability {
        DiskDurability::PerCommit => Durability::Immediate,
        DiskDurability::WriteBehind { .. } => Durability::None,
    }
}

The gRPC and WebChannel fronts, which the SDKs talk to, run disk commits one at a time on a blocking thread, off the async workers that serve reads. None of the five steps reads more than the documents being written, and none depends on how many listeners are open. That is most of the answer.

Durability: write-behind, not per commit

Skipping fsync does not lose writes when the process dies. The journal write hands the bytes to the operating system, which keeps them, and the next open replays every journal record newer than redb’s last durable revision, stopping at a torn tail by its checksum. Once a second, a thread called firenook-disk-flusher syncs the journal, makes one empty durable redb commit, which persists every earlier one, and truncates the journal; a clean stop does the same. A killed process loses no acknowledged write. A kernel crash or a power cut loses at most the last second.

--durability per-commit syncs on every commit instead. We measured the difference on an Apple M2 Pro laptop with Firestore alone, in the shape of the benchmark’s write check: 2,000 sequential writes through the Admin SDK, each confirmed by a listener, then 4,000 writes from eight writers at once. Two alternating rounds per mode, each on a fresh store:

Measured	Write-behind (default)	Per commit
Write, median	0.22–0.24 ms	14.7–14.9 ms
Write, 99th percentile	0.69–0.75 ms	22.9–23.5 ms
Listener update, median	0.33–0.35 ms	14.9–15.1 ms
Eight writers	10,151–11,068 writes/s	66–68 writes/s

Syncing every commit is right for data you cannot recreate. For emulator data, a one-second window on a power cut is a better trade than 60 to 66 times the write latency. The official emulator writes its data only when it exports, so a crash loses everything since the last export.

Indexes on the write path

Each write keeps three indexes. The collection and collection-group indexes take one entry each. The ordered field index takes one for every top-level field: its key is the collection and field, then the value encoded so that its bytes sort in the query engine’s order, then the document’s id. Integers and doubles share one numeric order, strings and bytes up to 64 bytes are keyed exactly, and longer ones by a prefix and a 16-byte digest. Arrays, maps and vectors are keyed by their type and whether they are empty, so an order over a field still reaches every document holding it. On an update, the commit reads the document’s current entries in the same transaction and writes only the difference.

That is a few small B-tree inserts per write. With Firestore alone on the benchmark server, on fresh copies of the same store, a write took 0.62 to 0.67 ms at the median, and eight writers reached 3,078 to 3,374 writes a second.

The index pays off on reads. An == or in filter reads only the documents holding the value, joining several filters by seeking each to the largest id any of them is at. An orderBy, a range or a cursor walks the field’s entries from the right place and stops once it has enough, checking equality filters on other fields against the index before it reads a document. In the benchmark an equality on a string field took 20.0 ms against 124 ms.

Memory that does not grow with the data

Firenook keeps documents in redb on disk, behind a page cache with a 64 MiB budget. After a commit, the store’s in-memory map of documents is empty again; what stays is the revision, recent commit times and the bounded change log. Over the two hours, Firenook’s process went from 1.64 GiB to 1.67 GiB. The official emulator, which keeps all its data in its Java heap, went from 15.42 GiB to 22.57 GiB, and used 1,586 s of CPU time against Firenook’s 616 s.

What the record does not show is where the official emulator’s 200 ms go. It measures both emulators from outside, and we will not guess at the inside of a JVM we did not profile. It does rule one explanation out: the official stack paged to swap during the run, but its write median, 208 ms, is within a few percent of an earlier run on the same server in which neither stack swapped.

Listener fan-out

A commit does not wait for listeners. Its observer publishes the new revision on a watch channel and returns. Each listen stream wakes on that channel, reads the change log since the revision it last saw, and for each key in its targets’ scope checks whether the document now matches. The view is updated in place, a document entering, changing or leaving, without running the query again. Only a document leaving a full limit window, or moving inside one, makes a target run its query, since only the store knows which document fills the gap. This work runs on a bounded pool of read threads, off the commit’s path.

In the benchmark, all 60,000 listener updates per emulator arrived, 11 ms after the write at the median on Firenook and 209 ms on the official emulator. One difference showed up: the official emulator notifies a listener about a document its filter excludes, and Firenook does not. A journey of the application that waited on such a notification ran longer on Firenook; it is not an emulator latency, and the benchmark leaves it out.

Ordered queries

Queries that order or range-filter a collection gain the most from the index. Without it, such a query reads every document in its scope, 10,918 here; with it, the walk stops at the 20 documents asked for, however large the collection:

Shape, median	Official	Firenook
orderBy an integer field, limit 20	96.3 ms	12.0 ms
orderBy a timestamp, descending, limit 20	109 ms	24.7 ms
Range on an integer field, limit 20	95.5 ms	13.2 ms
`==` plus orderBy on another field	99.3 ms	14.7 ms
Five cursor pages of 20	489 ms	74.8 ms

On the same data grown to 2.7 million documents, the four ordered and filtered queries measured there answered in 3 to 6 ms. The official emulator, on Java’s default settings, ran out of memory loading that data at the first query; with a 24 GiB heap it answered each in 8 to 28 seconds.

Firenook was faster on 25 of the 26 shapes and tied on the last: 500 document ids with no fields, 98.3 ms against 97.8 ms, because it reads each document whole before dropping its fields.

How it was measured

One AMD Ryzen 5 3600 server with 64 GiB and NVMe storage, on Ubuntu 24.04 and Node 24.20.0, ran one emulator at a time from a clean start, with nothing else running: firebase-tools 15.22.0 on Java 26 with its default settings, then Firenook with its defaults. Both had the same data, the same application revision and the same workload, and the run fails unless both end with identical data. An independent audit recomputed every figure from the raw samples.

The numbers are kept in benchmarks/020-paired-acceptance.json, and the benchmarks page has the method and its limits. It is one server and one application, so measure your own workload.

To use these write semantics for your own data, read Keep data between runs.

Introducing Firenook

Fri, 23 Oct 2026 00:00:00 GMT

Firenook is a drop-in replacement for the Firebase Local Emulator Suite. It reads your firebase.json, listens on the same ports and keeps your data between runs. 0.2.0 is its first release for public use. This post explains why it exists, what it does today, what it does not do yet, and how to try it on your project in three steps.

A day with the emulator

If you build on Firebase, the emulator suite is part of your day. You start it in the morning, point your app and your tests at it, and leave it running. It does its job: it behaves like production. But the day has costs you stop noticing.

Before the first start, you install Java, because the official Firestore emulator runs on it. Then the data lives in the Java heap, and the heap grows. In our benchmark of a real application, two hours of its traffic took the official emulator from 15.42 GiB of memory to 22.57 GiB.

When you stop it, the data is gone unless you exported it. Keeping it means --export-on-exit at every stop and --import at every start. On that application’s data, 211,205 Firestore documents and 6.7 GB in Storage, the export took 54 to 58 seconds and the next start 30.7 to 31.7 seconds. A crash loses everything since the last export.

Writes slow down under load, too. With the application running, its listeners open and its functions firing, the official emulator acknowledged a write in 208 ms at the median.

None of this is a bug. An emulator that keeps its data in memory needs the memory to hold it and an export to keep it. Firenook is what we built to remove those costs without changing anything else in your project.

What Firenook is

One npm package. Installing it adds a small launcher, and npm picks the native engine for your machine from its optional dependencies: macOS on Apple silicon or Intel, Linux x64 or arm64 with glibc 2.28 or newer, or Windows x64. Nothing else is downloaded, at install or at start: no Java, no firebase-tools, no emulator archives. Node runs your Functions, as it does in production, so the emulators need Node 22, 24 or 26.

The same project. Firenook reads firebase.json and .firebaserc the way the Firebase CLI does, and serves each emulator on the port you gave it: Firestore on 8080, Auth on 9099, Storage on 9199, Functions on 5001, Pub/Sub on 8085, Cloud Tasks on 9499 and Eventarc on 9299 by default. Your client and Admin SDKs connect unchanged, connectFirestoreEmulator and FIRESTORE_EMULATOR_HOST included. It imports and exports the official format, so your data moves both ways.

A native engine. The services are written in Rust, and Firestore keeps its data on disk, not in a heap. Add --keep-data and Firestore, Auth and Storage come back with all your data at the next start, with no export and no import. Every acknowledged write is durable within a second; how Firenook writes 40× faster walks through how, and how an ordered index answers orderBy, ranges and cursors.

A console. The Emulator UI’s port serves Firenook’s console, at http://127.0.0.1:4000/console. It has a page for every service the suite runs: Firestore and Storage to browse and edit, Auth users with an inbox of the sign-in codes and email links Auth would have sent, and every function call with what triggered it, its outcome, its duration and its logs. Pub/Sub, Cloud Tasks and Eventarc have pages too, where the official UI has only its log.

A terminal. In a terminal, emulators:start draws its own screen: the start-up, a ready summary, and a line for every function call, with the stack trace when one fails. Press o to open the console, r to reload your functions and q to stop, which saves your data first.

A new project in one screen. npx firenook init in an empty folder asks every question on one screen, with an answer already chosen for each: the project id, the emulators, TypeScript or JavaScript Functions, and your coding agent. Then it installs, builds and offers to start the emulators in the same terminal. --build compiles your TypeScript as you save.

An MCP server. firenook mcp gives a coding agent 54 tools over the running suite, from Firestore queries to the line of your Security Rules that denied a request. Give your coding agent the emulator shows a session.

What we measured

We ran one real application against each emulator in turn, on the same server, with the same data and two hours of the same traffic. Then we ran each emulator alone for starts, stops, 26 query shapes and a store of 2.7 million documents. The official emulator was firebase-tools 15.22.0 on Java 26 with its default settings, and Firenook ran with its defaults.

Measured	Official	Firenook
Memory at peak	22.57 GiB	2.11 GiB
Write, median	208.2 ms	5.1 ms
Listener update after a write, median	209 ms	11 ms
Start again with the data	30.7–31.7 s	0.59–0.60 s
Stop with the data saved	54–58 s	0.05–0.26 s
orderBy, limit 20, median	96.3 ms	12.0 ms
Emulator CPU time over the two hours	1,586 s	616 s

Firenook was faster on 25 of the 26 query shapes and tied on the last, 500 document ids with no fields. Queries that order or range-filter a collection are served from an ordered index: on 2.7 million documents they take 3 to 6 ms, where the official emulator ran out of memory on Java’s defaults and needed a 24 GiB heap and 8 to 28 seconds. Within the Storage cycle, downloads are still a little slower on Firenook: 2.30 ms against 2.12 ms at the median.

Every figure, the method and its limits are on the benchmarks page. It is one server and one application, so measure your own workload before you rely on the numbers.

What it does not do yet

0.2.0 is the first release we ask the public to use. Commit your lockfile and upgrade on purpose, as you would any tool your tests depend on. Before a release is published, it passes conformance replays against recorded behaviour of the official emulator and a packed install on all five platforms.

Some things are not there yet:

Realtime Database, Hosting, App Hosting and Data Connect are not emulated. A firebase.json that configures them still starts, with a warning, and the rest of the suite runs.
There is no functions:shell. firenook functions:invoke calls any function on the running suite instead, background triggers included.
There is no deploy or login command. Keep firebase-tools for deploying.
Linux with musl (Alpine) and Windows on Arm are not qualified.

The compatibility page records what each service covers and what it does not.

Try it in three steps

Install it in your project, next to firebase-tools:

npm install --save-dev firenook

Check your project. This reads firebase.json the way the Firebase CLI does and changes nothing:

$ npx firenook init --adopt --dry-run
Firenook init --adopt: ~/demo-shop/firebase.json
  add     give Claude Code the Firenook MCP server: ~/demo-shop/.mcp.json
Dry run: nothing was written.

It names any service Firenook skips and any addition it would make, such as a missing emulators entry or the MCP server for the coding agent the project uses. Without --dry-run, it applies the additions, and edits your files as text, so their formatting stays.

Swap the command. The flags, the ports and the export format stay the same, so your app and your data need no change:

"scripts": {
  "emulators": "firebase emulators:start --import ./data --export-on-exit",
  "test:integration": "firebase emulators:exec \"npm test\""
  "emulators": "firenook emulators:start --import ./data --export-on-exit",
  "test:integration": "firenook emulators:exec \"npm test\""
}

Once that works, you can stop exporting. Replace --export-on-exit with --keep-data: the first start imports ./data into .firenook/state, every later start picks up where you stopped, and ./data is never written. Add .firenook/ to your .gitignore.

Going back takes the same steps in reverse. While Firenook runs, export with npx firenook emulators:export ./export, stop it, and start the official CLI on that export.

Open source and independent

Firenook is open source under the Apache License 2.0, and the code is at github.com/firenook-dev/firenook. It is an independent project, not affiliated with or endorsed by Google. Firebase, Cloud Firestore and the other product names are trademarks of Google LLC.

Every change to Firenook is checked against recorded behaviour of the official emulator, and the differences it keeps on purpose are written down. If you find one that is not, or anything else that breaks on your project, open an issue.

To start, switch an existing project or set up a new one.

Give your coding agent the emulator, not production

Wed, 21 Oct 2026 00:00:00 GMT

A coding agent working on a Firebase app needs data, function calls and rules to look at before it can help. This post shows how to give it the local emulators instead of production, with firenook mcp: what the tools do, how to set them up, a real session, and what stays on your machine.

The problem

Ask an agent why a function fails, and it has two ways to answer. It can read the code and guess, which gets you a confident answer about a request it never saw. Or it can look for credentials, a service account key or a logged-in CLI, and query production. That puts your customers’ data in a prompt and lets an agent write where your real users are.

The emulators already hold what the agent needs: data in the shape your app writes it, the request that failed with its stack trace, the rule that denied a write. What is missing is a way for the agent to ask them.

What firenook mcp serves

firenook mcp is a Model Context Protocol server over stdio, part of the Firenook package, with no dependencies of its own. It reads firebase.json and .firebaserc from the folder the agent starts it in, so it needs no project id. It finds the running suite again on every call, so you can restart the emulators without restarting the agent.

It serves 54 tools, in groups:

Group	Tools	What the agent can do
Status	2	See how the project was found and which emulators run; export the data
Firestore	6	Get, query, count, write and delete documents; list collections
Auth	13	Create, list and delete users; read the email and SMS codes; mint ID tokens; set claims; disable users; list tenants
Storage	7	List, read, upload, copy, move and delete files; read metadata
Functions	5	List and invoke functions; read each call with its request, error and stack trace; replay a call
Logs	2	Search the suite’s log by service, level, function, call, text and time
Rules	3	Read the rules in force; ask whether a request would be allowed and which line decided; list recent denials
Pub/Sub	4	Publish; list topics and subscriptions; peek at a backlog without acknowledging it
Tasks and schedules	5	Read queue statistics and tasks; run a task or a schedule now
Eventarc and Extensions	6	Publish, list and replay events; list and reload Extensions instances
Reset	1	Clear the data of the services you choose

firenook mcp --only firestore,auth serves a subset; the two status tools are always there. The tool reference lists every tool with its arguments.

Set it up

From the project folder, with Firenook installed in the project:

npx firenook mcp add

It looks for Claude Code (a .claude/ folder, CLAUDE.md, an .mcp.json or claude on the PATH), Cursor (.cursor/) and VS Code (.vscode/), and writes each one’s project file. In our demo project:

$ npx firenook mcp add
Firenook mcp add: ~/demo-shop
  add     .mcp.json (Claude Code)
  add     .cursor/mcp.json (Cursor)
  add     .vscode/mcp.json (VS Code)
  Codex: codex mcp add firenook -- npx firenook mcp
Commit these files so every teammate's agent has the server; restart the agent to load it.

Each file gets one entry that runs npx firenook mcp:

{
  "mcpServers": {
    "firenook": {
      "command": "npx",
      "args": [
        "firenook",
        "mcp"
      ]
    }
  }
}

VS Code’s .vscode/mcp.json names the same entry under servers, with "type": "stdio". Other servers in those files are kept, and a second run changes nothing: it prints keep for each file that is already set. --dry-run shows what it would write, --agent cursor,vscode picks the agents, and --force replaces another firenook entry. An agent configured only in your home folder, such as Codex above, gets the line to run, and no file outside the project is edited.

Start the emulators as usual with npx firenook emulators:start, then restart the agent so it loads the server.

A session

The home page shows an agent answering a question about the demo shop: eight products, twelve customers, twelve orders through its checkout function, and one webhook sent without a signature. The question is an example; the tool calls and the answers are from a run of the demo project, trimmed.

The Stripe webhook answers 500 on my machine. Why?

The agent calls functions_list_calls with {"outcome": "failed"}:

{
  "total": 1,
  "calls": [
    {
      "id": "e72ca3-25",
      "function": "us-central1-stripeWebhook",
      "kind": "http",
      "summary": "POST /",
      "durationMs": 1.15,
      "outcome": "failed",
      "status": 500
    }
  ]
}

Then functions_get_call with that id, for the call in full:

{
  "error": "Unhandled error Error: No signatures found matching the expected signature for payload",
  "stack": "Unhandled error Error: No signatures found …\n    at functions/index.js:24:11\n    …",
  "request": {
    "method": "POST",
    "path": "/",
    "headers": {
      "host": "127.0.0.1:5001",
      "connection": "keep-alive",
      "content-type": "application/json",
      "accept": "*/*",
      "accept-language": "*",
      "sec-fetch-mode": "cors",
      "user-agent": "node",
      "accept-encoding": "gzip, deflate",
      "content-length": "37"
    },
    "body": { "type": "checkout.session.completed" }
  },
  "response": { "status": 500, "body": "Internal Server Error" }
}

The answer is in the request: it carries no stripe-signature header, and line 24 of functions/index.js throws when the header is missing. The agent found it without touching production.

We ran a second session on the same project for this post, about rules. Its Storage rules deny everything, and the question is whether a signed-in customer can upload a product photo. The agent calls rules_evaluate for a create of products/mug.jpg as the customer’s uid, with a 48,000-byte JPEG:

{
  "as": { "uid": "a6oK9eDRtwAa9RTryMc2ZTjEjKTm", "claims": {} },
  "allowed": false,
  "outcome": "deny",
  "decidedBy": [
    { "line": 9, "text": "allow read, write: if false;", "outcome": "deny" }
  ]
}

It drafts a rule and passes it as source, which evaluates the draft instead of the rules in force:

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products/{file} {
      allow read: if true;
      allow write: if request.auth != null
        && request.resource.contentType.matches('image/.*')
        && request.resource.size < 5 * 1024 * 1024;
    }
  }
}

The same request is now allowed, with the line that decided and the value of every expression on the way:

{
  "draft": true,
  "allowed": true,
  "outcome": "allow",
  "decidedBy": [
    { "line": 6, "text": "allow write: if request.auth != null", "outcome": "allow" }
  ],
  "steps": [
    { "line": 6, "expression": "request.auth != null", "value": "true" },
    { "line": 7, "expression": "request.resource.contentType.matches('image/.*')", "value": "true" },
    { "line": 8, "expression": "request.resource.size < 5 * 1024 * 1024", "value": "true" }
  ]
}

Without a uid, the same draft denies the request at line 6, where request.auth is null. Nothing was written: your storage.rules stays as it is until you accept the change. In this session, every tool answered in 0.8 to 18 ms.

Destructive tools keep the console’s safeguard. Asked to clear Firestore and Auth at once, emulators_clear refuses until the agent names the project:

{
  "error": "Clearing 2 services (firestore, auth) deletes all their data; to confirm, pass confirmProject: \"demo-shop\" (the project id)"
}

What stays on your machine

The server holds no credentials and contacts no cloud service. Every request goes to the emulators, at the addresses the hub or firebase.json gives.
It calls the emulators with the owner token the Admin SDK uses, so its reads and writes skip Security Rules, as the Admin SDK’s do. To ask about rules, the agent uses rules_evaluate, which writes nothing.
Each request carries an x-firenook-client: firenook-mcp/<version> header, and after each call the server tells the console which tool ran, so the console’s Connect dialog can show when an agent last called. Nothing else is recorded.
A demo- project id never reaches a real Firebase project. With a real project id the suite still contacts nothing, but your own function code can reach the real project if it holds credentials: Firenook is not a network sandbox.

The server gives the agent a better place to look, not a cage: an agent with a shell can still run what it likes. Treat what an agent writes through the server as you would any emulator data, synthetic only.

Read how agents use Firenook for an overview, and Connect your coding agent for the setup of each agent.