Skip to content

docs: add macOS/Apple Silicon setup FAQ - #371

Open
lgezz wants to merge 1 commit into
ossf:mainfrom
lgezz:docs/macos-faq
Open

docs: add macOS/Apple Silicon setup FAQ#371
lgezz wants to merge 1 commit into
ossf:mainfrom
lgezz:docs/macos-faq

Conversation

@lgezz

@lgezz lgezz commented Aug 25, 2026

Copy link
Copy Markdown

Summary

What this adds

A new FAQ documenting how to run OSS-CRS on macOS (Apple Silicon), covering
Docker Desktop + Rosetta setup and the most common Mac-specific errors.

Why

Setting up OSS-CRS on an Apple Silicon Mac surfaces several issues not covered in
the current docs. This FAQ is grounded in a confirmed working end-to-end run of
the crs-libfuzzer pipeline (prepare → build-target → run), producing seeds and
POVs — not speculation.

Contents

  • Setup & environment — Docker Desktop vs Colima on Apple Silicon
  • The three classic errors, with real root causes:
    • oss-crs-deps: pull access denied — a same-daemon / local-image-not-present
      problem (with docker_registry: local), not a missing registry image;
      includes the post-prepare verification step
    • Killed / exit 137 with empty stderr — ASAN/libFuzzer instability under QEMU
      emulation, resolved by enabling Rosetta
    • Requested CPUs are not available and the cpuset required-field
      constraint — how to set it for a Mac VM
  • oss-crs setup — Phase 2 cgroup behavior on macOS and how to proceed
  • Running the pipeline — command sequence, the docker-py vs CLI
    DOCKER_HOST gotcha, and how to confirm success via seeds/POVs

Testing / validation

The documented configuration (cpuset: "0-7", memory: "16G", Docker Desktop
with Rosetta, single daemon throughout) was used to complete a full run that
produced seeds and POVs, so the guidance reflects a working setup.

Notes

Signed-off-by: Laura Guazzelli <lguazzelli@linuxfoundation.org>
@lgezz

lgezz commented Aug 25, 2026

Copy link
Copy Markdown
Author

@azchin — would appreciate your review when you have a chance. Thanks!

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant