Engine shape

One thread serves and works: that is the default on every machine, and what a forge with FORGE_ENGINE unset runs. The split, which moves the engine's duties onto a Worker of the same process, is an optimisation and is asked for by name:

memory limit of at least 1024 MiB (or none known) give the split; anything less keeps one thread, since the Worker costs about 20 MiB and only pays with a core to spare. CPUs are what the scheduler offers held under the cgroup's quota (v2 cpu.max, else v1 cpu.cfs_quota_us/cpu.cfs_period_us), so a 1-CPU container on a big host counts as 1; memory is the smaller of the cgroup's cap (v2 memory.max, else v1 memory.limit_in_bytes) and the machine's.

Either ask is honoured only on Bun 1.4.4 or newer. Before it, bun:sqlite keeps the database handles of every thread in one table with no lock, and a Worker that opens the database beside the serving thread can end the process (#12538). On an older Bun the forge runs one thread and says so.

A hosted child, a read-only standby and a test boot stay on one thread whatever the variable says.

The default is a safety default for uptime, not a limit on work: the duties are the same on either shape. On 2026-11-14 a release chose the split from the machine's size alone and production restarted for 4.5 minutes at boot.

When the Worker cannot be had

The forge stays up. A Worker that cannot be made, cannot be told its settings, or dies 5 times inside 10 minutes is given up: the log says so in one line at error level, the serving thread takes the duties back, and the forge runs one thread until its next start. /system then reads one thread with what happened, and an admin's needs list carries one line linking there.

Which shape runs

Open /system and read "Engine shape", or open the System command in the terminal. Both read the same choice, made once at boot (engine/mode.ts), and the reason in words.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs