Skip to content

Feature request: configurable guest memory in the Start Menu #81

Closed

Description

@rdtiv

Feature request: configurable guest memory in the Start Menu

Motivation

The guest always boots with 4 GiB of RAM (-m 4G, hardcoded in
macos/run-qemu-gpu.sh). On Macs with 16–64 GiB, users who run browsers and
dev tooling inside Omarchy push the guest into zram swap while the host has
plenty of free memory. vCPUs already adapt to the host (up to 8), but memory
does not.

Current behavior

  • macos/run-qemu-gpu.sh passes -m 4G unconditionally; the startup log
    states "4 GiB RAM" as a fixed fact.
  • The guest runtime contract declares minimumMemoryMiB: 2048 and
    recommendedMemoryMiB: 4096.
  • The guest ships a zram swap device sized to RAM, which softens but does not
    remove the pressure.
  • Nothing in the Start Menu or environment lets the user change the
    allocation; the balloon device cannot grow past the boot-time -m value.

Proposal

Add a Memory row to the start menu, following the exact pattern the app
already uses for its other settings (UserDefaults preference store → an
OMARCHY_QEMU_GPU_* environment variable → re-validation in
run-qemu-gpu.sh). Since every launch begins at the start menu, one row
covers both moments that matter:

  • Configure at setup — the desired default behavior. The row is present
    on the very first start menu, before the first boot, so users decide how
    much RAM Omarchy gets as part of initial setup. Doing nothing keeps
    today's exact behavior (4 GiB).
  • Adjust after setup — explicitly supported. Because the start menu
    precedes every launch, changing memory later is the same one-click
    gesture: pick a new value, launch. This is technically trivial — memory is
    only a QEMU boot flag (-m), never baked into the guest image or the
    persistent VM data — so no reset, reinstall, or migration is ever
    involved.

The row:

Memory                                        4 GiB (default)
  Give Omarchy more of your Mac's RAM.
  Applies the next time Omarchy launches.
  ( 4 GiB · default )  ( 6 GiB )  ( 8 GiB )  ( 12 GiB )
  • The row offers a small fixed set of choices — e.g. {4, 6, 8, 12, 16} GiB —
    filtered so only values that leave the host at least 8 GiB of headroom are
    shown (hw.memsize via sysctl). On an 8 GiB Mac the row is effectively
    read-only at 4 GiB.
  • Default stays 4 GiB, so the zero-setup promise is untouched; the row shows
    "default" until the user changes it.
  • The choice persists in UserDefaults (mirroring
    PortForwardingPreferenceStore) and is exported as
    OMARCHY_QEMU_GPU_MEMORY_MIB.
  • run-qemu-gpu.sh re-validates the value independently (integer, ≥ the
    manifest's minimumMemoryMiB, ≤ a host-derived cap; anything invalid falls
    back to 4096 or fails loudly, matching the script's existing style) and uses
    it in -m and in the startup log line.
  • Applies on next launch only — no memory hot-plug; the launcher already works
    this way for its other settings. Only a live resize of a running VM is out
    of scope (virtio-balloon cannot grow past the boot-time -m value, and
    virtio-mem hot-plug is not worth the complexity here).

Implementation sketch

  1. macos/run-qemu-gpu.sh: read and validate OMARCHY_QEMU_GPU_MEMORY_MIB
    (default 4096), use it in the -m argument and the two startup log lines.
  2. macos/Sources/OmarchyVMHelper/: a MemoryPolicy + preference store
    (validation and host-cap logic in a deterministic model, per the testing
    guidance), environment injection alongside
    FullscreenPreferences/PortForwardPolicy, and a Start Menu row +
    StartMenuPresentation entry.
  3. Tests: model tests for clamping/filtering of choices; a
    OMARCHY_QEMU_GPU_DRY_RUN=1 script contract test asserting the -m value,
    like the existing macos/Tests/run-qemu-*.test.sh suites.
  4. README: document the new row and the env var.

Alternatives considered

  • Auto-scale memory like vCPUs — rejected as the default: a surprise
    jump in host memory pressure on small Macs; opt-in via the menu is safer.
  • Env var only, no UI — works for power users but invisible; the Start
    Menu already exists precisely for this kind of pre-launch choice.

Activity

  1. rdtiv commented on Sep 9, 2026

    @rdtiv
    Author

    implemented #82

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions