From d16e2ba4a87f3519f01b454e98ab93ef15779ef4 Mon Sep 17 00:00:00 2001
From: Dan Guido <dan@trailofbits.com>
Date: Mon, 26 Jan 2026 18:20:00 -0500
Subject: [PATCH] Add Colima optimization guide for Apple Silicon

Adds a collapsible section after Prerequisites with optimized
Colima settings (vz + virtiofs) that provide 5-10x faster file I/O
compared to defaults (QEMU + sshfs).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/README.md b/README.md
index c6acb22..0af23f9 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,37 @@ A pre-configured sandboxed development environment for Claude Code with `--dange
   - [Docker Desktop](https://docker.com/products/docker-desktop) - ensure it's running
   - [Colima](https://github.com/abiosoft/colima): `brew install colima docker && colima start`
 
+<details>
+<summary><strong>Optimizing Colima for Apple Silicon</strong></summary>
+
+Colima's defaults (QEMU + sshfs) are conservative. For better performance:
+
+```bash
+# Stop and delete current VM (removes containers/images)
+colima stop && colima delete
+
+# Start with optimized settings
+colima start \
+  --cpu 4 \
+  --memory 8 \
+  --disk 100 \
+  --vm-type vz \
+  --vz-rosetta \
+  --mount-type virtiofs
+```
+
+Adjust `--cpu` and `--memory` based on your Mac (e.g., 6/16 for Pro, 8/32 for Max).
+
+| Option | Benefit |
+|--------|---------|
+| `--vm-type vz` | Apple Virtualization.framework (faster than QEMU) |
+| `--mount-type virtiofs` | 5-10x faster file I/O than sshfs |
+| `--vz-rosetta` | Run x86 containers via Rosetta |
+
+Verify with `colima status` - should show "macOS Virtualization.Framework" and "virtiofs".
+
+</details>
+
 ## Quick Start
 
 ### Option 1: VS Code / Cursor