Configure memory for the JITX runtime#

Increase the runtime heap limit when a design exhausts its current limit and the host has enough free memory. The setting caps the native runtime’s managed heap. Memory used by Python, the editor, and other processes is additional. Measure memory use and leave capacity for the operating system and other work.

Choose the setting#

The CLI and VS Code launch paths accept JITX_INTERACTIVE_MAX_HEAP_SIZE. They copy its value to STANZA_MAX_HEAP_SIZE in the native runtime process. If both are set, the interactive value takes precedence for that child process. There is no requirement to make one half the other.

Use one positive whole-number value in gigabytes, such as 32. Do not add a unit suffix or decimal fraction. The examples below illustrate a 32 GB cap; choose a smaller value when the host cannot accommodate that heap plus its other processes. A larger cap does not guarantee faster routing or fix every crash.

Variable	Use
`JITX_INTERACTIVE_MAX_HEAP_SIZE`	Set this for a runtime started through the JITX CLI or VS Code extension.
`STANZA_MAX_HEAP_SIZE`	Underlying Stanza heap setting. It can affect other Stanza processes; set it separately only when that is intended.

Apply a temporary limit#

Run these commands from the project root with its pinned Python environment activated. Changing a shell variable does not change an already-running process. Finish ongoing work, stop the project’s runtime, set the variable, and restart it from that same shell.

Windows PowerShell:

jitx runtime stop
$env:JITX_INTERACTIVE_MAX_HEAP_SIZE = "32"
jitx runtime start --background
jitx runtime status

macOS or Linux:

jitx runtime stop
export JITX_INTERACTIVE_MAX_HEAP_SIZE=32
jitx runtime start --background
jitx runtime status

Restart any jitx design session after restarting its runtime. Other projects may have their own runtime processes and memory budgets.

For a runtime launched by the VS Code extension, fully quit the editor first, set the variable, and start a fresh editor process from that shell:

code .

A new window attached to an existing editor process may retain the old environment. The code command must be on PATH; otherwise use the editor executable’s full path. In PowerShell, a quoted path needs the call operator, for example & "C:\Program Files\Microsoft VS Code\Code.exe" ..

Make the setting persistent#

On Windows, add JITX_INTERACTIVE_MAX_HEAP_SIZE under your account’s User variables in the Environment Variables dialog, then start a fresh terminal and editor. Use a system-wide variable only when your administrator intends it for all users.

On macOS or Linux, add the export to the startup file for the shell that launches JITX, such as ~/.zshrc or ~/.bashrc:

export JITX_INTERACTIVE_MAX_HEAP_SIZE=32

Open a fresh shell afterward. Shell startup files do not necessarily affect applications launched from a desktop icon or a service. Configure the environment at the actual runtime launch point.

To remove the temporary override, use Remove-Item Env:JITX_INTERACTIVE_MAX_HEAP_SIZE in PowerShell or unset JITX_INTERACTIVE_MAX_HEAP_SIZE in a POSIX shell. Remove any persistent definition too, then restart the runtime. Check for a separately set STANZA_MAX_HEAP_SIZE if the old limit still applies.

Verify the runtime process#

For a runtime started with jitx runtime start, runtime status reports the native launcher PID and log path. The CLI maps the heap variable before launching that process. Inspect that PID and, when diagnosing memory use, its design-worker children. Inspecting only the Python CLI or editor does not show the native runtime’s environment. For a runtime launched elsewhere, status may show an unknown PID; locate the native jitx process in the process tree.

On Windows, use Microsoft Process Explorer, open the runtime process properties, and inspect its Environment tab. Check that STANZA_MAX_HEAP_SIZE has the intended value.

On macOS or Linux, inspect the runtime’s environment locally:

ps eww -p PID

Replace PID with the reported process ID. On Linux, /proc/PID/environ is another source when permissions allow it. Process environments can contain credentials; avoid copying the full output into a support message. Record only the relevant heap values.

Observe the process’s memory use while reproducing the design operation. If the process reaches the cap, the machine starts swapping heavily, or the same error persists, retain the runtime log path from jitx runtime status and investigate that specific failure.