Memory Limits

Once limits the memory pressure created by concurrent local actions. By default, it schedules against two thirds of the memory visible to the host or container. This leaves room for Once itself, the operating system, editors, and other processes.

Override the budget for any command with --memory-limit:

The value above is two gibibytes. You can also write it as 2GiB, where GiB is the abbreviation defined by the International Electrotechnical Commission binary-prefix standard. Raw byte counts and decimal unit suffixes are accepted too.

The option is global, so these forms are equivalent:

How Scheduling Uses The Budget#

Each local action reserves its declared memory estimate before it starts. Actions without an estimate reserve 250 mebibytes. Once admits more work only when the combined reservations fit within the configured budget. An action whose estimate exceeds the entire budget runs alone instead of waiting forever.

The same budget applies to builds, lint targets, run targets, literal commands, annotated scripts, and test workers. Internal subprocesses inherit an explicit limit, so nested test and agent-tool invocations do not reset to the machine default.

Cache capture, command error output, and cached output restoration stream large files through bounded buffers and temporary files. Artifact size therefore does not become a same-sized memory allocation during these operations.

What The Limit Guarantees#

This is an admission-control budget based on action estimates, not a hard operating-system memory ceiling. It bounds Once's scheduling decisions and its own artifact buffering. A command that uses more memory than its estimate can still exceed the budget by itself.

Use a container or operating-system process limit when a command must be forcibly stopped at an exact resident-memory boundary. Pair that hard boundary with a lower Once budget so the scheduler leaves enough headroom for the Once process and the operating system.

Choosing A Value#

Start with the automatic default. Set a lower value in a small container or on a shared machine where other services need predictable headroom. If builds become unnecessarily serial, raise the limit gradually and declare realistic memory estimates for unusually small or large actions.

The active value is recorded in verbose internal logs as memory_limit_bytes, together with the default estimate used for actions that do not declare one.