homarr/docs/perf/SERVER-MEMORY.md

Server memory: what the container's RAM is made of

Measured with scripts/benchmarks/stress-restore.mts on a restored real backup. See METHODOLOGY.md for the tools and the measurement traps, and REJECTED.md for everything that was tried and abandoned.

Metric choice

memory.current moved between 192 and 261 MiB for the same baseline image across runs, because cgroup v2 counts reclaimable page cache. At idle that split was 144 MiB anon vs 77 MiB page cache. Everything below therefore reports anonymous memory, which was stable to ±2.5 MiB across repeated runs of the same image.

Attribution — this is the part that matters

Built cumulatively from the baseline image, one change at a time:

config	boot idle anon	verdict
baseline	139.2	—
+ integrations barrel diet	139.5	no idle effect
+ Redis clients 6 → 2	139.3	no idle effect
+ serverExternalPackages: mysql2, pg	118.6	−21 MiB — the entire idle win
branch (everything)	115.2 / 99.0	no further gain beyond the above

change	diff size	idle	under load
serverExternalPackages + mysql2/pg	1 line	−21 MiB	−25 MiB
integrations barrel diet	~10 files, +119 lines	~0	−40 MiB (±25 noise)
Redis clients 6 → 2	4 files	~0	~0
V8 heap cap (HOMARR_MAX_OLD_SPACE_SIZE=512)	1 line	~0	~0
cache invalidation + next-cache-handler	~30 files, 66 call sites, ~290 lines	0	0

Why one config line beats the whole module-graph refactor

packages/core/src/infrastructure/db/drivers/index.ts statically imports all three drivers, so mysql2 and pg are in the graph even when DB_DRIVER=better-sqlite3. Bundled, their full transitive graphs are inlined into the boot-loaded server chunks; marked external they become a require() that the sqlite path never reaches. Verified inside the images:

image	server chunks	mysql2 in node_modules
baseline	108,336 KB	no — it was inlined into the chunks
+ external pkgs	94,936 KB	yes — traced, loaded only on demand
branch	98,084 KB	yes

This is fix-catalog F6 ("load only the configured DB driver") achieved by one config line, after the dynamic-import() attempt was reverted for breaking Vitest.

The V8 heap cap is a safety ceiling, not a reduction

branch-cap4096 (cap effectively removed) matched branch at every stage — idle 99.0 vs 115.2, board loaded 230.2 vs 228.1, after stress 362.6 vs 358.8. The workload never approaches a 512 MB old space, so the cap cannot reduce steady-state usage. It is still worth keeping as one line: baseline's soak hit a 543.8 MiB anon sample, and capped baseline topped out at 347.5 MiB, which is exactly the unbounded-drift protection issue #5301 needs. It should not be described as a memory saving.

The cache layer is provably dead code

On the current branch state there are 0 "use cache" directives, 0 cacheTag(), 0 cacheLife(), 0 unstable_cache, and no tagged fetch in application source — and cacheHandlers/cacheComponents have both been removed from next.config.ts. packages/next-cache-handler is referenced only by a package.json dependency line; nothing imports it. The 66 remaining invalidate* call sites call revalidateTag on tags nothing ever registers, with no handler to receive them, inside a try/catch that swallows the resulting out-of-scope error. Zero functional effect, ~30 files of churn.

What is actually hogging the memory

Tested directly against the hypothesis that cached base64 images were bloating TanStack Query / Redis. They are not — measured on a loaded 4-tab session:

suspect	measured	verdict
base64 data-URLs in server heap	0.01 MiB (2 strings)	not a factor
base64 blobs in browser heap	0.01 MiB (7 strings)	not a factor
Redis total	2.17 MB	not a factor
image bytes in Redis	none — image-proxy stores only URL + headers	not a factor
React Query gcTime	already 5 min, not 24 h	already addressed

What the server heap is actually made of (141 MiB used, 259 MiB RSS):

bucket	size	share of heap
bundled JS source retained as strings	41.4 MiB	~29%
other strings (translations, ids, misc)	10.3 MiB	7%
URLs	2.0 MiB	1%
everything else (objects, code, maps)	~87 MiB	62%

The memory is the code, not cached data. That is why every cache-tuning idea in the fix catalog measured at zero, and why serverExternalPackages — which removes code from the boot-loaded bundle — was the only lever that moved idle memory.

Correction (later round). An earlier version of this section claimed "7.86 MiB is literal duplicate copies" of identical chunk sources. That figure was wrong. It came from grouping heap-snapshot strings by content, but V8 truncates string contents to ~1 KiB when serialising a snapshot, so the comparison only ever saw each string's first kilobyte and reported near-identical chunks as identical. Hashing the real files found zero byte-identical duplicates among all 3,055 .next/server/**/*.js files (77.6 MiB). The chunks that looked like copies are distinct files that happen to begin with the same vendored module. The real doubling has a different cause — see "Why the source costs twice what it should" below.

@ioredis/commands is now external, which removes it from all 10 chunks. Recorded as bundle hygiene, not a memory win: idle went 89.7 → 89.4 MiB, inside noise, and board-loaded/peak differences were smaller than the run-to-run spread (one "before" run read 220.6 MiB against 169–173 for identical code).

got and @octokit/request-error were deliberately not externalised. They are only transitive dependencies here, and a check inside the image confirmed got is not traced into node_modules — externalising it would have turned a bundled module into a runtime require that resolves to nothing, trading zero measured gain for a possible MODULE_NOT_FOUND on a code path the benchmarks never hit.

Where the remaining headroom is

Nothing further is available from caches, Redis, or process trimming. The two real levers left are both large:

1. Ship less server JavaScript. ~29% of the heap is retained bundle source. Every package moved out of the boot graph pays twice — smaller chunks and less retained source. This is the same lever that produced the −37% idle result.
2. Stop the App Router re-rendering every second (see above). That governs the browser side, which is where the 650 MB peak lives.

Full attribution — every megabyte, top to bottom

Everything above measured totals. This section measures composition: each layer is reconciled against the one above it, so nothing hides in a rounding gap. Tooling: scripts/benchmarks/attribute-memory.mts (cgroup → processes → mappings → V8 spaces → loaded code) with scripts/benchmarks/memory-probe.cjs injected as a --require preload.

The probe is diagnostics-only and is never in a shipped image: the harness mounts scripts/benchmarks at /probe and sets NODE_OPTIONS=--require /probe/memory-probe.cjs.

Layer 1 — the container is one process

process	RSS at steady state
next-server	188.1 MiB (95%)
redis-server	4.8 MiB
nginx (2 procs)	3.7 MiB
shells	1.3 MiB

Redis and nginx are rounding errors. Every question about Homarr's memory is a question about one Node process.

Layer 2 — where that process's RSS lives

Measured from /proc/<pid>/smaps. Anonymous mappings cannot be told apart by size, so they are classified by signature: V8 allocates its heap in 256 KiB pages (kRegularPageSize), and pthread reserves ~8 MiB per thread stack.

At boot idle (139 MiB RSS):

region	RSS	what it is
node binary (code)	54.3 MiB	the Node runtime's own text pages — file-backed and shared, so it counts in RSS but not in cgroup anon
V8 heap pages (256 KiB each)	47.8 MiB	the JS heap
native malloc / small V8 spaces	28.2 MiB	musl arenas, Buffers
V8 code range / trusted space	4.8 MiB
JIT code (anonymous executable)	1.8 MiB	machine code V8 compiled
better_sqlite3.node	2.0 MiB	the only native addon that matters
thread stacks	0.1 MiB resident	48 MiB reserved, essentially untouched

This explains the single most confusing number in the whole exercise: RSS 139 MiB but cgroup anon only 89 MiB. The 54 MiB gap is the Node binary itself. It is reclaimable page cache shared with every other Node process on the host, so it is real RSS but not a real cost — which is exactly why anon is the metric this PR reports.

Address space reserved but not committed: 16.8 GiB. V8 claims its cage up front. It is not memory.

Layer 3 — inside the JS heap

V8 space	boot idle	after real use
old_space	42.0 MiB	97.2 MiB
large_object_space	22.7 MiB	27.3 MiB
code_space + code_large	1.9 MiB	10.9 MiB
trusted_space	3.9 MiB	8.1 MiB
new_space	0.0 MiB	0.2 MiB
external (Buffers)	4.1 MiB	22.0 MiB

Layer 4 — what those objects are

From a post-GC heap snapshot at steady state (143.8 MiB heapUsed, 1.39M nodes):

bucket	size	share of heap
bundled JS source retained as strings	41.0 MiB	28%
ArrayBuffer backing stores	17.6 MiB	12%
object property/element arrays	16.4 MiB	11%
other strings (translations, ids)	10.3 MiB	7%
closures	5.7 MiB	4%
plain objects	4.5 MiB	3%
shapes/maps/descriptors	6.6 MiB	5%
compiled code metadata	~12 MiB	8%

Confirmed again, with a dominator-tree analysis this time (scripts/benchmarks/analyze-heap-dominators.mjs, real retained sizes rather than shallow histograms): the largest single retainers are code: nodes named after chunk files, each holding 0.5–1.4 MiB, i.e. the Script objects keeping their own source alive. V8 retains a script's source string for as long as any function in it might still be lazily compiled.

The memory is the code, not cached data.

Why the source costs twice what it should

.next/server chunks loaded at boot are 21.7 MiB on disk, but the heap holds 32.4 MiB of source strings. The gap is not duplication — it is character width.

A V8 string is either one byte per character (Latin-1) or two. One character above U+00FF anywhere in a file forces the entire source string to two bytes.

loaded JS	files	on disk	heap cost
pure Latin-1	1,025	12.25 MiB	12.25 MiB
contains ≥1 char > U+00FF	80	9.45 MiB	18.91 MiB

Predicted total 31.16 MiB against 32.43 MiB measured — within 4%.

Proven directly rather than inferred, by reading one chunk as shipped and again with its non-Latin-1 characters replaced (identical length):

_049nb9n._.js  538,519 chars, 2 of them non-Latin-1
  as shipped      : 1053 KiB per copy -> 2.00 bytes/char
  ascii variant   :  526 KiB per copy -> 1.00 bytes/char

Two characters cost 527 KiB. The offenders are almost all trivia in dependencies:

chunk	non-ASCII chars	the actual characters
_049nb9n._.js (+2 siblings)	2	process.versions.icu?"✅":"Y "
[root-of-the-server]__1ipwvlq._.js	13,141	Next's log symbols ○ ⨯ ⚠
_1ew9xg8._.js (+ssr twin)	70,175	a UTF-8 self-test containing 💩
zod chunks ×4	13,137	✖ ${i.message}
app-page-turbo.runtime.prod.js	13	an ellipsis …
[root-of-the-server]__1xyzm2f._.js	13	an em-dash in Homarr's own MCP instructions

Total recoverable: ~9.45 MiB of heap (≈10% of idle anon), by emitting server bundles with \uXXXX escapes instead of raw characters. Not implemented here — it means rewriting minified vendor output at build time, and the safety argument needs to be made properly before that ships. Recorded as a measured, mechanistically understood opportunity.

The peak: one integration was allocating 46 MiB per refresh

The steady state above is ~237 MiB RSS. The peak during a 4-tab session was 429 MiB RSS / 539 MiB container, and that peak is a completely different phenomenon.

Per-stage V8 accounting (scripts/benchmarks/analyze-probe-stages.mjs):

stage	rss	old_space	external	arrayBuffers
boot idle	138.6	42.0	4.1	0.3
board loaded	254.9	95.3	22.9	3.0
nav ×3	361.9	122.5	24.7	4.8
4 tabs, 2 boards	429.3	152.6	114.3	94.3
after 90 s idle	237.0	97.2	22.0	2.0

arrayBuffers goes 0.3 → 94.3 → 2.0. It is entirely transient — which is precisely why the app appears to "oscillate between 835 MB and 400 MB" and never settles at the high mark. Soak growth was −102 MiB/hour: there is no leak.

Tracking large Buffer allocations by stack (HOMARR_PROBE_TRACK_BUFFERS) put 48.3 MiB in 16 allocations at one site, with a single allocation of 46.3 MiB:

T (/app/apps/nextjs/.next/server/chunks/_1q3xovl._.js:92:32374)
process.processTicksAndRejections

That function is undici's fullyReadBody — the machinery behind Response.json():

async function T(A,e,t){ let r=[],s=0; for(;;){ let{done:i,value:o}=await A.read();
  if(i) return void e(Buffer.concat(r,s)); r.push(o), s+=o.length } }

It holds the chunk list and the joined copy at the same moment, so a body of size N costs ~2N at the instant it completes. Capturing the bytes identified the response immediately:

46.3 MiB assembled from 3,946 socket chunks
{"data":[{"id":"1251f6db…","websiteId":"f133f10c…","sessionId":"9e02d227…","createdAt":"2026-08-09T…

Umami. And the cause was in plain source — two call sites requesting pageSize: "100000", i.e. up to 100,000 raw event records:

1. getEventNamesAsync downloaded every raw event of the last 30 days to collect a handful of distinct event name strings.
2. getWebsiteEventTimeSeriesAsync downloaded them to bucket them into a time series.
3. getMultiEventTimeSeriesAsync ran (2) for every tracked event name concurrently via Promise.all, multiplying the resident pages by the number of events.

A board with 3 Umami widgets and several tracked events therefore had several ~46 MiB bodies in flight at once, each briefly doubled, plus ~100k parsed objects per response landing in old_space. That is the 500–880 MB.

The fix

call site	before	after
getEventNamesAsync	list 100k raw events, collect distinct names	aggregated /metrics?type=event, one row per name
getWebsiteEventTimeSeriesAsync	one page of up to 100k records	pages of 1,000, folded into buckets and released
getMultiEventTimeSeriesAsync	Promise.all over all event names	sequential

The paging path keeps the existing dual-shape handling: instances that return aggregated {x,y} buckets still answer in one request, and an instance that accepts pageSize but ignores page is detected (repeated first record id) and stopped rather than double-counted. Hitting the page ceiling logs a warning instead of silently undercounting.

Covered by packages/integrations/src/umami/test/umami-integration.spec.ts (6 tests, new — there were none).

Result

Alternated runs, 2 before and 2 after, same harness and workload, before = branch HEAD f707f6433, after = HEAD + this change. Per-run values are given because the harness's own spread is what decides whether a difference means anything.

metric	before	after	change	before spread / after spread
peak container	498.9 MiB	398.5 MiB	−20%	[461.6, 536.3] / [387.0, 410.0]
peak node RSS	452.4 MiB	353.3 MiB	−22%	[432.7, 472.2] / [355.6, 350.9]
peak during 4 tabs	498.5 MiB	356.3 MiB	−29%	[460.8, 536.3] / [341.8, 370.8]
peak arrayBuffers	95.8 MiB	6.6 MiB	−93%	[95.7, 95.8] / [6.4, 6.7]
largest single allocation	46.4 MiB	2.4 MiB	−95%	identical in both runs
post-soak steady state	324.2 MiB	322.5 MiB	−1%	[337.7, 310.7] / [280.7, 364.4]
boot idle	119.4 MiB	125.8 MiB	+5%	[130.0, 108.8] / [152.8, 98.8]
median board load	526 ms	523 ms	−1%	[389, 663] / [401, 645]
CPU over the run	19.5 s	20.4 s	+4%	[19.6, 19.4] / [20.3, 20.4]

Every peak metric separates cleanly — the two sides' ranges do not overlap. Two rows do not support a claim and are listed so they are not read as one:

• post-soak steady state is inconclusive. One "after" run finished at 364.4 MiB, above a "before" run at 310.7. This change targets a transient spike, so a steady-state effect was not expected.
• boot idle is noise. The spread is ±20 MiB on identical code (before: 130.0 vs 108.8), which is wider than the apparent difference. Umami's code is not even loaded at boot; it arrives when a board containing the widget renders.

The cost is +4% CPU, from turning one large request into several smaller ones. Board load latency did not regress.

A prediction worth recording, because it confirms the mechanism rather than just the outcome: at pageSize=1000 the largest allocation measured 0.7 MiB, and at 5,000 it measured 2.4 MiB — 5× the page size, 3.4× the bytes, exactly as a per-page bound implies.

What the real instance revealed

Widget readiness is identical before and after — 28/28 on the board carrying the three Umami widgets, and the same single pre-existing error on the other board — so nothing broke. But the container log from the "after" runs contains something the "before" runs could not have produced:

warn: Event time series hit the page ceiling, counts are a lower bound
      module="umami-integration" eventName="Add app" maxRecords="100000"

That site really does have more than 100,000 events for one event name in the window. The old code had exactly the same ceiling — pageSize=100000 is 100k records — and the 46.3 MiB body it received was that ceiling being hit. The difference is that it truncated in silence and reported the undercount as fact. The ceiling is unchanged; it is now visible.

This is also the worst case for the round-trip trade-off: that one event name costs 20 sequential requests. It did not show up in board load latency (523 ms vs 526 ms median), because the widget fetches after the board renders, and total CPU rose 4%.

Dissecting the peak, not the idle

Everything above measures a drained process — boot idle, or post-soak. That is the wrong moment: users complain about the high-water mark. Measuring it needs different instruments, because the obvious one cannot work.

A heap snapshot can never explain a peak. V8 runs a full GC before serialising one, so by construction it reports what survived. The 94 MiB of ArrayBuffers that drove this container to 500 MB was invisible in every snapshot taken. Three instruments were added instead:

instrument	what it sees	blind to
HeapProfiler.startSampling (in-process inspector.Session)	every V8-heap allocation, survivor or garbage, with a stack	anything outside the V8 heap
wrapped Buffer.alloc/concat	external buffer allocations, with a stack	V8-heap objects
/proc/<pid>/smaps at every stage	JS heap vs JIT vs native vs file-backed	anything below page granularity

Together they cover the whole address space. Neither of the first two alone would have found the Umami bug: the sampling profiler cannot see Buffer backing stores, which is precisely where those 46 MiB lived.

An observer effect worth recording

The first attempt took the peak snapshot over CDP, which delivers it as JS string chunks. For a ~135 MB snapshot that added ~134 MiB of ArrayBuffers to the process being measured, and the stage right after it read 693.7 MiB. That is an artefact, not an application problem — and it is exactly the kind of number that gets reported as a finding. Switching to v8.writeHeapSnapshot, which streams from C++, removed it. The probe now reports its own observerCostMiB so the cost of looking is visible rather than assumed to be zero.

What the peak is actually made of

Peak here is nav-01, not the multi-tab stage — a GC lands during multi-tab and pulls RSS down, so "most tabs open" is not the same as "most memory". Node RSS 357.8 MiB:

component	MiB	notes
live JS objects (heapUsed)	175.7	of which ~41 MiB is retained bundle source
node binary text	65.7	file-backed and shared; not in cgroup anon
native malloc	~59	see below
external buffers	24.6
V8 committed but free	12.3	heapTotal − heapUsed
JIT code	10.1	grew from 1.9 MiB at boot

Cross-checked rather than assumed: heapTotal 188.0 − V8's 256 KiB pages 153.1 = 34.9 MiB, which matches large_object_space at 34.5 MiB. So the handful of very large anonymous mappings (31.6, 20.7, 8.4 MiB) are V8's large-object space and external buffers — not the runaway native allocator that their shape first suggested.

The retained heap at peak is the same as at rest. A post-GC snapshot at peak has 160.7 MiB of shallow size against 157.7 MiB after the soak; strings 51.1 vs 50.1 MiB. Nothing accumulates. The peak is transient churn plus pages V8 and malloc have not returned — which is why memory "oscillates" and why soak growth is negative.

And the churn is small now: total V8-heap allocation across the entire run is 125 MiB, 40% of it node's own module loader reading source files. After the Umami fix the multi-tab burst allocates 3.3 MiB. There is no longer a churn problem on the JS side.

The 16 MiB nobody was using: ssh2

The largest single retainer in every snapshot — at boot, at peak, and after the soak — was one system / Context holding 16.03 MiB. Expanding it through the dominator tree (a plain graph walk escapes via __proto__ and reports the whole heap) named it immediately:

=== inside the largest retainer (object:system / Context, 16.03 MiB) ===
     16.00 MiB  (indirect) -> object:ArrayBuffer
      0.00 MiB  POLY1305_WASM_MODULE -> object:Object
      0.00 MiB  ChaChaPolyCipherNative -> closure:ChaChaPolyCipherNative
      0.00 MiB  AESGCMCipherNative -> closure:AESGCMCipherNative

ssh2. Its crypto module instantiates a WebAssembly memory for ChaCha20-Poly1305 the moment it is required. Homarr has no SSH feature and does not depend on ssh2; the chain is dockerode → docker-modem → ssh2, and docker-modem/lib/modem.js requires ./ssh at module scope while using it in exactly one place, already guarded by protocol === 'ssh'.

Measured directly inside the image — requiring ssh2 and nothing else:

heapUsed  +2.6 MiB     external  +0.9 MiB     rss  +14.0 MiB

Fixed with a pnpm patch moving that one require inside the branch that uses it. SSH-based Docker hosts still work — require is cached, so they pay it once — and socket-based installs, which is everyone else, never load it.

The same question asked of every dependency

Since one package was hiding 14 MiB behind a require, all 173 were measured the same way: each required in a fresh process, RSS delta recorded. Packages costing more than 2 MiB, cross-checked against whether the server actually loads them:

package	RSS to require	loaded at runtime?
drizzle-orm	124.3 MiB	only via subpaths — the root import loads every dialect, so this figure overstates it
@kubernetes/client-node	66.9 MiB	no — correctly lazy
dockerode	28.8 MiB	yes (includes docker-modem 16.1 and ssh2 14.3)
mysql2	20.9 MiB	yes — 77 files, on a SQLite install
sharp	20.4 MiB	no
openid-client / jose	16.1 / 15.5 MiB	no
@grpc/grpc-js	14.6 MiB	yes, 61 files (via dockerode)
pg	9.4 MiB	yes — 13 files, on a SQLite install

These are not additive — dockerode's figure contains ssh2's — but the ranking is what matters.

Correction. The RSS figures in the table above were measured without forcing a GC between readings, so they include V8 growing its heap opportunistically rather than the real cost of the module. Re-measured with global.gc() before each reading, the two unused database drivers cost 21.4 MiB RSS / 4.1 MiB heap, not the ~30 MiB the naive sum implied — and drizzle-orm's 124.3 MiB was almost entirely this artefact. The ssh2 conclusion is unaffected: it was confirmed independently by the before/after external-memory drop.

mysql2 and pg load on every SQLite install — and it was not worth fixing

db/drivers/index.ts statically imports all three driver wrappers and picks one at call time, so importing the module executes all three. Confirmed at runtime: mysql2 (77 files) and pg (13 files) are resident on a SQLite install. Re-measured properly, the prize is 21.4 MiB.

Three attempts, each caught by testing the real image rather than by typecheck:

1. createRequire(import.meta.url) — this module is bundled into two entry points, and db/migrations/<dialect>/migrate.cjs is CommonJS, where import.meta.url compiles to undefined. createRequire threw ERR_INVALID_ARG_VALUE at load and took down migrations, and therefore startup, for every dialect including SQLite. Fixed by basing resolution on process.cwd().
2. With that fixed, MySQL failed with MODULE_NOT_FOUND on drizzle-orm/mysql2/index.cjs. A dynamic require resolves through the package's require condition to a .cjs build, and Next's tracing only ever copied the ESM index.js into the standalone output.
3. Leaving drizzle's dialect as a static import defeats the purpose entirely: drizzle-orm/mysql2 itself does from "mysql2", so the client loads anyway. Verified — the built image still loaded all 77 mysql2 files.

That leaves two routes, and both are worse than the problem. Forcing drizzle's .cjs into the image via outputFileTracingIncludes would load a second copy of drizzle's core next to the ESM one for MySQL users, so class identities and is() checks would straddle two module instances. Requiring the ESM file works under Node 24's require(esm) — but only via an absolute path (/app/node_modules/drizzle-orm/mysql2/index.js); both bare specifiers fail, so it would hardcode drizzle's internal file layout and a drizzle upgrade would break startup for MySQL and Postgres users.

Backed out. 21.4 MiB is not worth a startup-failure class of risk on two dialects that cannot be exercised in normal development. The blocker to record is structural: createDb must stay synchronous because packages/db/index.ts does export const db = createDb(schema) at module scope and migrate.cjs is CommonJS, so neither await import() nor top-level await is available. Making the database handle async would unblock it.

Why 24 MiB of code is resident before the first request

The module cache is a flat list with no parentage, so "what pulled this in" needed the require graph recorded as the loader resolves it (HOMARR_PROBE_TRACK_REQUIRES=1, analysed by scripts/benchmarks/analyze-require-graph.mjs). At boot idle, having served only /api/health/ready: 2,004 edges over 1,121 nodes, 23.97 MiB of source.

importer	subtree
apps/nextjs/server.js (everything)	23.83 MiB / 1,087 files
next/dist/server/load-components.js	21.75 MiB / 796 files
[root-of-the-server]__0g06wx7._.js	16.10 MiB / 460 files
next's own framework code, exclusively	2.16 MiB / 315 files

Two things follow, and the second is the one that matters:

1. Next loads all 74 app route bundles at startup, not on first request. That is framework behaviour, not something this codebase sets. That was wrong — see below.
2. One subtree of 16.10 MiB / 460 files is reached by the tRPC/API routes and by instrumentation — the cron tasks and websocket server. Exclusive attribution for instrumentation is therefore 0 bytes: everything it touches, an API route touches too. Only 1.10 MiB / 119 files is common to every route, so this is not one universal barrel — it is specifically the API surface pulling in every integration and widget request handler.

That kills the obvious fix. Deferring instrumentation would free nothing, because Next preloads /api/[...trpc] at boot and that route reaches the same graph. Cutting the shared subtree itself requires the tRPC router to stop referencing every integration eagerly — the same lever the integrations barrel diet started, with roughly 16 MiB of source still behind it.

Correction: preloading is configurable, and turning it off is the largest idle win here

The claim above that route preloading is "framework behaviour, not something this codebase sets" was wrong. Next documents experimental.preloadEntriesOnStart: false for exactly this, and the guide describes it as preventing the server from preloading page modules into memory at startup. Found by reading Next's own memory-usage guide rather than by inference — which is the lesson.

Deterministic per-stage measurements, identical across both runs on each side:

stage	source loaded	files	heapUsed
boot idle	24.0 → 10.6 MiB	1114 → 706	70.7 → 44.8 MiB (−37%)
post-login	27.9 → 19.3 MiB	1215 → 884	123.8 → 109.8 MiB
board loaded	29.0 → 21.7 MiB	1323 → 1006	run-to-run noise
multi-tab	29.2 → 22.9 MiB	1325 → 1015	139.7 → 127.8 MiB
post-soak	29.2 → 22.9 MiB	1325 → 1015	142.5 → 127.4 MiB

The last two rows are the important ones: 310 files and 6.3 MiB of source stay unloaded even after a full multi-tab session, so this is not merely deferred cost — routes a session never visits are never paid for at all. Live heap is lower at every stage.

Peak node RSS does not move (350.3 → 346.1, spreads overlap), for the same reason the ssh2 chop did not move it: V8 sizes its heap against available headroom, so a smaller live set does not shrink peak RSS. Median board load is +3% with overlapping spreads, so the first-hit cost this trades for did not show at this workload. Full E2E suite passes 8/8.

Also from that guide, and not applicable here: webpackMemoryOptimizations, serverSourceMaps, enablePrerenderSourceMaps and disabling the Webpack cache all address build-time memory, and this build uses Turbopack.

--jitless: rejected, and the reason generalises

V8's --jitless removes the optimising compiler and all generated machine code. It applies through NODE_OPTIONS and its effect on code memory is real and unambiguous: code space 11.6 → 0.0 MiB. The stress figures looked spectacular — peak node RSS −24%, peak container −36%, CPU −14%, median board load 30% faster.

Three of those are impossible. The flag was applied to the server, so it cannot make the browser lighter, and removing an optimising compiler does not make code faster. The client metrics show what actually happened:

	normal	jitless
DOM nodes	8,256 / 8,280	5,442 / 5,442
JS event listeners	7,781 / 7,784	1,570 / 1,570
browser JS heap	50.0 / 49.5 MiB	28.1 / 28.2 MiB
widget controls available	244	216

Boards still reported 28/28 widgets ready, so the coarse readiness check passed — but the page carries 80% fewer event listeners. Much of the UI never mounted. The memory "win" is an app doing less work, and the CPU and latency "improvements" are the same artefact.

The generalisable tell: when a server-side change moves a client-side metric, the workload changed and the comparison is void.

Flags that cannot be used this way at all: --optimize-for-size, --no-opt and --lite-mode are rejected by Node with "not allowed in NODE_OPTIONS".

Closing the last gap: what the native bucket at peak actually is

At peak the smaps bucket "other anonymous" holds 118.8 MiB and was the least understood part of the footprint. It is now mostly accounted for:

component	MiB	how it was established
V8 large_object_space	34.5	heapTotal 188.0 − the 256 KiB pages 153.1 = 34.9, matching the space report
external — Buffers/ArrayBuffers	24.6	process.memoryUsage()
freed-but-unreturned V8 zone memory	~38	peak_malloced_memory 4.6 → 42.2 MiB at the board-loaded stage, while current malloced_memory stays at 1.0 MiB
unattributed native malloc	~22	remainder

The zone figure is the interesting one. V8 mallocs ~38 MiB of parser/compiler zone memory while compiling the board's modules, frees it back to malloc, and musl never returns it to the kernel — so it stays resident as anonymous memory with nothing alive in it.

A prediction that was wrong

The obvious inference — loading fewer files means less compiler zone memory, so "ship less server JS" pays twice — does not hold. peak_malloced_memory measured across the preloadEntriesOnStart A/B:

stage	before ×2	after ×2
boot idle	4.5, 4.5	4.5, 4.5
post-login	4.5, 4.5	4.5, 4.5
board loaded	42.1, 42.3	42.1, 42.1

Identical, despite 310 fewer files being loaded. The 38 MiB spike is a fixed cost incurred at board load, not a per-file one — one large parse or compile, not the sum of many. So the "pays twice" claim is withdrawn; preloadEntriesOnStart saves retained source and live heap, and does nothing for the native bucket.

The zlib-orphan hypothesis: disproven here

Next's own source documents a real leak class: a zlib stream left open by a client disconnect is pinned by its native handle, survives GC, and permanently retains ~256 KiB of deflate state. releaseCompressionStream, the fix, is not present in this Next build, and a peak heap snapshot showed 16 Zlib and 15 Gzip objects — 14 still there at idle, which looked exactly like accumulation.

It is not. process.getActiveResourcesInfo() reports Zlib=0, both at baseline and after 300 deliberately aborted gzip requests, with RSS flat at 136.5 MiB. Those snapshot entries are heap objects, not live handles — an important distinction, since a snapshot happily lists objects with no live native resource behind them. nginx buffers the response from Next, so Next never observes the mid-response client disconnect that creates an orphan in the first place.

Recorded because the initial reading of the snapshot was wrong in a way that would have shipped a fix for a leak this deployment does not have.

The 38 MiB of compiler zones: attributed, then found to be unaddressable

The largest single item in the peak breakdown that was never explained is now explained, and then closed off.

It is V8's optimising compiler. peak_malloced_memory jumps from 4.5 MiB to 42.1 MiB the moment a board's modules are compiled, while current malloced_memory stays at 1.0 MiB — memory V8 takes for compilation, frees back to malloc, and that musl never returns to the kernel. Proven by re-reading the --jitless runs, where the spike never happens at all:

stage	normal	--jitless
boot idle	4.5 MiB	4.5 MiB
board loaded	42.1 MiB	4.5 MiB
multi-tab	42.7 MiB	4.5 MiB

--jitless itself is unusable (it leaves the page under-rendered — see above), but V8 can cap the tier instead of removing code generation: --max-opt=3 is the default Turbofan, 2 stops at Maglev, 1 at Sparkplug. It is rejected by NODE_OPTIONS but accepted on the command line, so it was wired behind HOMARR_MAX_OPT and A/B'd on one image.

--max-opt=2 is a null result for memory:

stage	full	capped at Maglev
peak anon	276.0 MiB	282.8 MiB (+2%)
boot idle	64.0 MiB	72.3 MiB (+13%)
board loaded	186.1 MiB	179.2 MiB (−4%)
4 tabs	270.8 MiB	238.5 MiB (−12%)
after soak	199.0 MiB	214.3 MiB (+8%)
CPU	28.1 s	27.8 s (unchanged)

Render integrity was checked explicitly this time, because that is how --jitless was caught: listeners were 7,784 in all four runs and DOM nodes within 40 of each other, so unlike jitless the page rendered fully and the comparison is valid. There is simply no consistent memory win — some stages better, some worse, peak unchanged.

The mechanism says why, and it is worth recording as a closed door. Measured directly with the probe under --max-opt=2:

01-boot-idle     peak_malloced=  4.5 MiB
03-post-login    peak_malloced=  4.5 MiB
04-board-loaded  peak_malloced= 42.1 MiB   <- identical to Turbofan

Maglev's zone allocation is just as large as Turbofan's. Capping the tier does not reduce zone memory; only not compiling at all does, and that breaks the page. So this 38 MiB is not reachable through V8 configuration — it is proportional to how much JavaScript V8 has to compile, which puts it back under the one remaining server-side lever: ship less server code. Reverted.

Correction: the "16 MiB tRPC subtree" lever was already removed

Earlier rounds identified a 16.10 MiB subtree of 460 files reached by every API route and named it the one remaining lever with real headroom, attributing it to the tRPC router importing every integration eagerly. Both halves of that are now known to be wrong.

The integration creator was already fully lazy. Every kind in packages/integrations/src/base/creator.ts is () => import(...), so no integration class is loaded until one is constructed. The earlier "integrations barrel diet" had already done this properly; the claim that the router imports them eagerly was never checked against the code.

The subtree itself was an artefact of route preloading. That measurement was taken before preloadEntriesOnStart: false shipped, when Next loaded the module graph of all 74 routes at startup. Re-measured on the current build, boot is 706 files and 10.56 MiB of source, and it breaks down as:

owner	size	files	can it be reduced?
.next/server/chunks (app code)	3.73 MiB	28	this is the app's own boot graph, already lean at 28 chunks
better-sqlite3	2.16 MiB	14	no — 2.1 MiB of it is the native .node binary, and it is the default driver
next/dist (framework)	1.75 MiB	359	no — framework, and flat regardless of load
next/dist/compiled (vendored)	1.58 MiB	25	no
mysql2 + pg	0.52 MiB	90	yes in principle, but structurally blocked — see REJECTED.md
everything else	< 0.5 MiB	—	noise

So there is no single large server-side lever left. What remains is diffuse: under a full multi-tab session the app loads 15.44 MiB of its own chunks across 241 files, and that is what the ~41 MiB of retained source and the ~38 MiB of compiler zones both scale with. Reducing it means shipping less application JavaScript per route — a broad refactor with no single target, not a 16 MiB subtree waiting to be cut.