Why is OrbStack suddenly using 8,000+ file descriptors and breaking everything?

This is the [file descriptor leak bug](https://github.com/orbstack/orbstack/issues/1253) that bites large container setups. Happens when you have multiple containers with heavy bind mounts - each file gets a descriptor that doesn't get cleaned up properly.Quick fix: `lsof -p $(ps aux | grep OrbStack | head -1 | awk '{print $2}')` to see the mess, then restart OrbStack.Real fix: Upgrade to 1.6.2+ where this got patched. If you're stuck on older versions, limit concurrent containers or switch to named volumes for data-heavy apps.

OrbStack worked fine yesterday, now containers won't start after macOS update

Classic virtualization framework fuckery. macOS updates regularly break the hypervisor APIs that OrbStack depends on. Usually happens with .1 or .2 point releases - macOS 14.1.1 was fine, but 14.1.2 nuked everything with `com.apple.security.hypervisor` entitlement failures until OrbStack got patched.Immediate workaround: `sudo rm -rf ~/Library/Group\ Containers/HUAQ24HBR6.dev.orbstack/data/vz` then restart OrbStack. You'll lose running containers but images stay.Better approach: Check [OrbStack releases](https://orbstack.dev/docs/release-notes) before updating macOS. They usually push compatibility updates within days.

File syncing is suddenly slow as shit - bind mounts taking forever

The [VirtioFS optimization](https://orbstack.dev/blog/fast-filesystem) in OrbStack 1.6+ is great until it isn't. Usually caused by:1. **Thousands of tiny files**: Node modules, Python venvs, Go mod cache2. **File watchers going crazy**: Hot reload tools scanning everything3. **macOS Spotlight indexing**: Your containers triggering filesystem indexingFix the common culprits:```bash# Exclude from Spotlight (run on macOS)sudo mdutil -i off ~/OrbStack# Add .dockerignore to your projectsecho "node_modules\n.git\n*.log" >> .dockerignore# Use named volumes for package cachesdocker run -v npm-cache:/root/.npm your-app```

Memory leak in editors when opening files from OrbStack containers

[Known issue with text editors](https://github.com/zed-industries/zed/discussions/36529) accessing files through the `~/OrbStack` mount. VS Code, Zed, and others can balloon to 20GB+ RAM.Don't: Open files directly from `~/OrbStack/[container]/` in your editorDo: Copy files out first or edit inside the containerBetter: Use `docker exec -it [container] vim /path/to/file` for quick edits

"Cannot connect to Docker daemon" but OrbStack is running

Your Docker context is fucked. This happens when switching between OrbStack and Docker Desktop repeatedly. You'll get `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?` even though OrbStack is clearly running.```bash# Check current contextdocker context ls# If it shows orbstack but OrbStack isn't runningdocker context use default# If OrbStack is running but context is wrongdocker context use orbstack```Pro tip: `alias docker-reset='docker context use orbstack && docker system prune -f'` for when everything goes sideways.

OrbStack eating 100% CPU on Apple Silicon doing nothing

Usually the Rosetta x86 emulation getting stuck in a loop. Happens with poorly behaved x86 containers that don't clean up processes properly - I've seen this exact pattern with old Node.js containers that spawn child processes and never reap them, causing `qemu-x86_64` to go nuts.```bash# Find the culprit containerdocker stats --no-stream# Check if it's an x86 containerdocker inspect [container] | grep Architecture# Kill it with firedocker kill [container] && docker rm [container]```Prevention: Use native arm64 images whenever possible. Add `--platform=linux/arm64` to your docker run commands.

Containers can't reach the internet after connecting VPN

Corporate VPNs that route everything through proxies break OrbStack's networking. Unlike Docker Desktop, OrbStack follows macOS routing rules exactly.First try: Restart OrbStack after connecting to VPNIf that fails: Check if your VPN has split tunneling and exclude container trafficNuclear option: `orb restart` forces network stack resetTest connectivity:```bash# From containerdocker exec -it [container] curl -I https://google.com# Check DNSdocker exec -it [container] nslookup google.com```

OrbStack crashed and took all my running containers with it - how do I recover?

Unlike Docker Desktop, OrbStack doesn't have persistent container state across crashes. When OrbStack crashes hard (kernel panic, force quit), running containers are gone but images and volumes survive.```bash# Check what surviveddocker imagesdocker volume ls# Your compose files still workdocker compose up -d# But you lost any ephemeral data in containers```**Prevention**: Use named volumes for anything important. Don't rely on container filesystem for persistent data.

Why do my M1 containers run like garbage on M2/M3 Macs?

Apple Silicon optimization differences. OrbStack builds containers optimized for specific ARM variants, and M1-optimized containers don't get the full benefit of M2/M3 performance improvements. **Check your container architecture**: ```bash docker inspect [image] | grep -A5 Architecture ``` **Force rebuild for your specific chip**: ```bash docker build --platform=linux/arm64 --no-cache . ``` **Signs you have architecture mismatch**: - Container works but feels sluggish - High CPU usage for simple operations - Memory usage higher than expected

Large Docker Compose setups randomly fail to start all services

Resource contention during startup. OrbStack's single-VM approach means all containers compete for the same kernel resources during boot. **Symptoms**: - Some services start, others time out - Database connections fail intermittently - Network between containers unreliable **Fix the startup race**: ```yaml services: database: # Start DB first, give it resources deploy: resources: limits: memory: 2G healthcheck: test: ["CMD", "pg_isready"] interval: 5s timeout: 5s retries: 5 app: depends_on: database: condition: service_healthy # Wait for DB ``` **Or stagger the startup**: ```bash docker compose up database -d sleep 10 docker compose up -d ```

File operations work in containers but break when accessing from macOS Finder

The `~/OrbStack` mount is read-only from macOS for some file types, or has permission mismatches that only show up when accessing from the host. **Permission debugging**: ```bash # Inside container ls -la /path/to/file stat /path/to/file # From macOS ls -la ~/OrbStack/[container]/path/to/file stat ~/OrbStack/[container]/path/to/file ``` **Common permission patterns that break**: - Files owned by container root (UID 0) can't be edited from macOS - Scripts marked executable in container aren't executable from macOS - Symlinks created in containers point to wrong paths from macOS **Workarounds**: ```bash # Fix ownership from inside container docker exec -it [container] chown $(id -u):$(id -g) /path/to/file # Or copy files out for editing docker cp [container]:/path/to/file ./local-file # Edit local-file docker cp ./local-file [container]:/path/to/file ```

Containers can reach some external services but not others

OrbStack inherits macOS network configuration exactly, including enterprise firewalls, content filters, and proxy auto-config. This creates weird patterns where some external services work and others don't. **Debug the network path**: ```bash # Test from container docker exec -it [container] traceroute google.com docker exec -it [container] curl -v https://api.github.com # Compare with macOS traceroute google.com curl -v https://api.github.com ``` **Common patterns**: - HTTP works, HTTPS doesn't (corporate certificate issues) - Some domains resolve, others don't (split DNS) - Connections timeout inconsistently (proxy auto-config) **Enterprise network fixes**: ```bash # Bypass proxy for container traffic docker run --env HTTP_PROXY="" --env HTTPS_PROXY="" [image] # Use explicit DNS docker run --dns=1.1.1.1 --dns=8.8.8.8 [image] # Test without any macOS network inheritance docker run --network=none [image] # (then configure manually) ```

Build context uploads are slow even with .dockerignore

OrbStack still has to scan the entire build context before applying `.dockerignore`, and macOS filesystem calls are the bottleneck. **Build context size matters more than you think**: ```bash # Check actual context size docker build --no-cache . 2>&1 | grep "Sending build context" # Find the biggest directories du -sh * | sort -hr ``` **Optimize build context**: ```bash # Build from a subdirectory docker build -f ../Dockerfile . # Use multi-stage builds to avoid copying dev dependencies FROM node:alpine as builder COPY package*.json ./ RUN npm ci --only=production FROM node:alpine COPY --from=builder /app/node_modules ./node_modules ``` **When .dockerignore isn't enough**, create a separate build directory: ```bash mkdir docker-build rsync -av --exclude='node_modules' --exclude='.git' . docker-build/ docker build docker-build/ ```

Why does OrbStack use more battery than Docker Desktop on Intel Macs?

Counter-intuitive but true: OrbStack's efficiency optimizations are designed for Apple Silicon. On Intel Macs, the virtualization overhead is higher and thermal management is worse. **Intel Mac reality check**: - Docker Desktop: Heavy but predictable power usage - OrbStack: Lower idle usage, higher peak usage during builds - Battery life difference: minimal (10-15% at most) **Intel-specific optimizations**: ```bash # Limit build parallelism docker build --cpus="2" . # Use buildx for better resource control docker buildx build --cpu-period=100000 --cpu-quota=200000 . ``` If battery life is critical on Intel Macs, Docker Desktop might actually be better. The OrbStack advantage really shows on Apple Silicon.

Currently viewing the AI version

Switch to human version

OrbStack Performance Troubleshooting: AI-Optimized Technical Reference

Critical System Failures and Recovery

File Descriptor Leak (High Severity)

Problem: File descriptor leak bug affects large container setups with heavy bind mounts
Breaking Point: 8,000+ file descriptors causes system-wide failures
Root Cause: Each file gets descriptor that doesn't clean up properly
Affected Versions: Pre-1.6.2
Quick Diagnostic: lsof -p $(ps aux | grep OrbStack | head -1 | awk '{print $2}')
Immediate Fix: Restart OrbStack (temporary)
Permanent Fix: Upgrade to 1.6.2+
Prevention: Limit concurrent containers or use named volumes for data-heavy apps

Container Startup Failures After macOS Updates

Problem: macOS updates break hypervisor APIs regularly
Pattern: .1 or .2 point releases commonly cause issues
Example: macOS 14.1.2 broke com.apple.security.hypervisor entitlements
Emergency Recovery: sudo rm -rf ~/Library/Group\ Containers/HUAQ24HBR6.dev.orbstack/data/vz
Prevention: Check OrbStack releases before updating macOS
Recovery Time: OrbStack usually patches within days

Memory Leak in Text Editors

Problem: VS Code, Zed balloon to 20GB+ RAM when opening files from ~/OrbStack/ mount
Avoid: Direct file access from ~/OrbStack/[container]/
Workaround: Copy files out or edit inside container
Command: docker exec -it [container] vim /path/to/file

Performance Specifications and Limits

VirtioFS Performance Metrics

Optimal Performance: 75-95% of native macOS speed
Real-World Impact: 5-25% slower than native execution
Package Installation: pnpm install at 88% native speed (vs 40% Docker Desktop)
Large Files: 87% native performance (vs 60% Docker Desktop)
Database Operations: 76% native speed with proper fsyncing
Performance Cliff: Thousands of small files cause dramatic slowdowns

Memory Consumption Patterns

Default Limit: 8GB system memory (dynamic allocation)
Idle Usage: ~100MB
Single Rails App: 1-2GB total
Multiple Microservices: 4-6GB common
Large Databases: 3-4GB each (Postgres, MongoDB)
Critical Threshold: 16GB MacBook Pro with 6 containers can exceed available memory

CPU Overhead by Architecture

Native ARM64: 0-2% overhead vs native
x86 through Rosetta: 15-30% overhead
Build Performance: ARM64 Docker builds 2-3x faster than x86
Database Performance: Postgres ARM64 vs x86 shows 40% performance difference
Node.js Applications: 30% faster cold start times on native architecture

Resource Requirements and Scaling Limits

File Descriptor Consumption

Bind Mounts: 10-50 descriptors per mounted directory
Database Connections: 1-3 descriptors each
Network Connections: 2 descriptors per active connection
macOS Default: 256 per process (insufficient)
Recommended: 4096-8192 descriptors
Monitor Command: lsof -p $(pgrep OrbStack) | wc -l

Container Scaling Thresholds

8-12 containers: Optimal resource sharing
15-20 containers: Noticeable slowdowns from resource competition
25+ containers: Single VM becomes bottleneck
Failure Patterns: Random restarts, OOM kills, network timeouts

Configuration That Works in Production

Corporate Network Compatibility

Problem: OrbStack inherits macOS network configuration exactly
VPN Issues: Corporate VPNs that route everything through proxies break networking
DNS Problems: Split DNS creates inconsistent domain resolution
Proxy Auto-Config: PAC files add 200ms to every HTTP request
Certificate Issues: Corporate HTTPS inspection breaks container requests

Network Performance Fixes

# Bypass proxy for containers
docker run --env HTTP_PROXY="" --env HTTPS_PROXY="" [image]

# Use explicit DNS
docker run --dns=1.1.1.1 --dns=8.8.8.8 [image]

# Test connectivity
docker exec -it [container] time curl -I https://google.com

Optimization for File-Heavy Workloads

# Exclude from Spotlight indexing
sudo mdutil -i off ~/OrbStack

# Use named volumes for package caches
docker run -v npm-cache:/root/.npm your-app

# Optimize build context
docker build --cpus="2" .

Critical Warnings and Breaking Points

Single VM Architecture Limitations

Resource Competition: All containers share same kernel resources
Cascade Failures: One bad container can affect all others
Memory Pressure: OOM killer can terminate multiple containers
I/O Contention: High-throughput containers saturate shared interface

Performance Monitoring Commands

# Real memory pressure
orb exec --machine=default -- free -h
orb exec --machine=default -- cat /proc/pressure/memory

# I/O contention
orb exec --machine=default -- iostat 1 5
orb exec --machine=default -- iotop -ao

Docker Context Issues

Problem: Context switching between OrbStack and Docker Desktop
Error: "Cannot connect to Docker daemon" despite OrbStack running
Fix: docker context use orbstack
Reset Alias: alias docker-reset='docker context use orbstack && docker system prune -f'

When OrbStack Becomes the Bottleneck

Migration Indicators

Startup Time: Full environment exceeds 2-3 minutes
Resource Exhaustion: Random container restarts or OOM kills
Network Issues: Timeouts between containers on localhost
File Operation Failures: Previously working operations now timeout

Alternative Considerations

Docker Desktop: Better resource isolation at scale (25+ containers)
Intel Macs: Docker Desktop may provide better battery life
Enterprise Networks: Docker Desktop handles corporate networking better
Development/Production Parity: Performance differences more pronounced with OrbStack

Diagnostic Commands Reference

# Check container architecture
docker inspect [container] | grep Architecture

# Monitor real resource usage
docker system df
orb info

# Debug network performance
docker exec -it [container] time nslookup google.com
docker exec -it [container] ip route

# Find memory usage in containers
docker exec -it [container] ps aux --sort=-%mem

# Check build context size
docker build --no-cache . 2>&1 | grep "Sending build context"

Recovery Procedures

OrbStack Crash Recovery

Check surviving resources: docker images, docker volume ls
Restart services: docker compose up -d
Critical: Ephemeral container data is lost
Prevention: Use named volumes for persistent data

High CPU Usage (x86 Emulation)

Identify culprit: docker stats --no-stream
Check architecture: docker inspect [container] | grep Architecture
Kill problematic container: docker kill [container] && docker rm [container]
Prevention: Use --platform=linux/arm64 flag

Network Connectivity Issues

Test basic connectivity: docker exec -it [container] curl -I https://google.com
Check DNS: docker exec -it [container] nslookup google.com
Restart network stack: orb restart
VPN Workaround: Restart OrbStack after VPN connection

OrbStack Performance Troubleshooting: AI-Optimized Technical Reference

Critical System Failures and Recovery

File Descriptor Leak (High Severity)

Container Startup Failures After macOS Updates

Memory Leak in Text Editors

Performance Specifications and Limits

VirtioFS Performance Metrics

Memory Consumption Patterns

CPU Overhead by Architecture

Resource Requirements and Scaling Limits

File Descriptor Consumption

Container Scaling Thresholds

Configuration That Works in Production

Corporate Network Compatibility

Network Performance Fixes

Optimization for File-Heavy Workloads

Critical Warnings and Breaking Points

Single VM Architecture Limitations

Performance Monitoring Commands

Docker Context Issues

When OrbStack Becomes the Bottleneck

Migration Indicators

Alternative Considerations

Diagnostic Commands Reference

Recovery Procedures

OrbStack Crash Recovery

High CPU Usage (x86 Emulation)

Network Connectivity Issues

Related Tools & Recommendations

Colima - Docker Desktop Alternative That Doesn't Suck

Podman Desktop - Free Docker Desktop Alternative

Docker Desktop Critical Vulnerability Exposes Host Systems

Docker Desktop Became Expensive Bloatware Overnight - Here's How to Escape

Docker Desktop Security Problems That'll Ruin Your Day

Docker Compose 2.39.2 and Buildx 0.27.0 Released with Major Updates

Deploy Django with Docker Compose - Complete Production Guide

Rancher Desktop - Docker Desktop's Free Replacement That Actually Works

I Ditched Docker Desktop for Rancher Desktop - Here's What Actually Happened

Podman Desktop Alternatives That Don't Suck

RAG on Kubernetes: Why You Probably Don't Need It (But If You Do, Here's How)

GitOps Integration Hell: Docker + Kubernetes + ArgoCD + Prometheus

Kafka + MongoDB + Kubernetes + Prometheus Integration - When Event Streams Break

Google Vertex AI - Google's Answer to AWS SageMaker

Google NotebookLM Goes Global: Video Overviews in 80+ Languages

VS Code Settings Are Probably Fucked - Here's How to Fix Them

VS Code Alternatives That Don't Suck - What Actually Works in 2024

VS Code Performance Troubleshooting Guide

Figma Gets Lukewarm Wall Street Reception Despite AI Potential - August 25, 2025

GitHub Actions Marketplace - Where CI/CD Actually Gets Easier