OrbStack (Docker on Mac) — SKILL.md

---
name: "OrbStack (Docker on Mac)"
description: "Skill for OrbStack (Docker on Mac) — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "infrastructure"
agents: ["claude-code", "codex", "gemini"]
tags: ["orbstack", "infrastructure", "auto-generated"]
---

# OrbStack (Docker on Mac)

---
name: OrbStack (Docker on Mac)
description: Use when working with Docker containers on macOS, especially for development environments requiring better performance than Docker Desktop
metadata:
  author: skynet
  version: 1.0.0
category: infrastructure
---

# OrbStack (Docker on Mac)

## Overview

OrbStack is a fast, lightweight Docker Desktop alternative for macOS that provides better performance and resource usage for container development.

## Installation & Setup

### Install OrbStack
```bash
# Download from https://orbstack.dev or use Homebrew
brew install orbstack

# Start OrbStack
open /Applications/OrbStack.app
```

### Migration from Docker Desktop
```bash
# Export existing images
docker save $(docker images -q) -o docker-images.tar

# After installing OrbStack, import images
docker load -i docker-images.tar

# Verify migration
docker images
docker ps -a
```

## Core Operations

### Container Management
```bash
# Run container with volume mounting
docker run -d -p 3000:3000 -v $(pwd):/app --name myapp node:18

# Execute commands in running container
docker exec -it myapp bash
docker exec myapp npm install

# View container logs with follow
docker logs -f myapp

# Stop and remove container
docker stop myapp && docker rm myapp
```

### Image Operations
```bash
# Build image with BuildKit features
docker build -t myapp:latest .
docker build --platform linux/amd64,linux/arm64 -t myapp:multi-arch .

# Pull specific platform images
docker pull --platform linux/amd64 nginx:alpine

# Clean up unused images
docker image prune -a
docker system prune -a --volumes
```

## OrbStack-Specific Features

### Linux Machine Access
```bash
# Access OrbStack Linux environment directly
orb

# Run commands in Linux context
orb -c "apt update && apt install -y curl"

# Copy files to/from Linux machine
orb push myfile.txt /home/
orb pull /home/myfile.txt ./
```

### Performance Optimization
```bash
# Check OrbStack status and resource usage
orb status

# Configure resource limits
orb config set cpu_limit 4
orb config set memory_limit 8G

# Enable/disable features
orb config set kubernetes false
orb config set rosetta true  # For x86 containers on Apple Silicon
```

## Development Workflows

### Docker Compose Development
```bash
# Start development stack
docker-compose up -d

# Scale specific services
docker-compose up -d --scale worker=3

# View logs for specific service
docker-compose logs -f web

# Rebuild and restart service
docker-compose up -d --build web

# Clean shutdown
docker-compose down -v
```

### Multi-Platform Builds
```bash
# Setup buildx for multi-platform
docker buildx create --use --name orbstack-builder

# Build for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest --push .

# Build and load locally
docker buildx build --platform linux/arm64 -t myapp:arm64 --load .
```

## Decision Trees

### Choose Container Runtime Strategy
```
Development Environment?
├─ Local development only
│  └─ Use: docker run with volume mounts
├─ Multi-service application
│  └─ Use: docker-compose
├─ Kubernetes development
│  └─ Use: orb config set kubernetes true
└─ Production simulation
   └─ Use: Multi-platform builds + resource limits
```

### Performance Optimization Path
```
Performance Issues?
├─ Slow container startup
│  ├─ Enable Rosetta: orb config set rosetta true
│  └─ Use smaller base images
├─ High memory usage
│  ├─ Set memory limits: orb config set memory_limit 6G
│  └─ Clean unused resources: docker system prune -a
├─ Slow file operations
│  ├─ Use delegated mounts: -v $(pwd):/app:delegated
│  └─ Consider bind mounts for large codebases
└─ Network latency
   └─ Use host networking: --network host
```

## Troubleshooting

### Common Error Messages

**Error: "Cannot connect to the Docker daemon"**
```bash
# Check OrbStack status
orb status

# Restart OrbStack service
orb restart

# Verify Docker context
docker context ls
docker context use orbstack
```

**Error: "No space left on device"**
```bash
# Check disk usage
docker system df

# Clean up aggressively
docker system prune -a --volumes
docker builder prune -a

# Check OrbStack disk usage
orb status --verbose
```

**Error: "Platform mismatch warnings"**
```bash
# Enable Rosetta for x86 containers on Apple Silicon
orb config set rosetta true

# Explicitly specify platform
docker run --platform linux/amd64 myimage:latest

# Use multi-arch images when available
docker pull --platform linux/arm64 postgres:15
```

**Error: "Port already in use"**
```bash
# Find process using port
lsof -i :3000

# Kill process or use different port
docker run -p 3001:3000 myapp:latest

# Use dynamic port allocation
docker run -P myapp:latest
```

### Performance Issues

**Slow Build Times**
```bash
# Enable BuildKit cache
export DOCKER_BUILDKIT=1

# Use cache mounts in Dockerfile
# RUN --mount=type=cache,target=/root/.npm npm install

# Build with cache from registry
docker buildx build --cache-from myapp:buildcache .
```

**High Resource Usage**
```bash
# Monitor resource usage
docker stats

# Set container resource limits
docker run -m 512m --cpus="1.0" myapp:latest

# Configure OrbStack limits
orb config set memory_limit 4G
orb config set cpu_limit 2
```

### File Permission Issues
```bash
# Fix ownership in bind mounts
docker run -u $(id -u):$(id -g) -v $(pwd):/app myapp:latest

# Use named volumes for persistent data
docker volume create myapp-data
docker run -v myapp-data:/data myapp:latest

# Set proper permissions in Dockerfile
# USER node
# WORKDIR /app
```

### Network Connectivity
```bash
# Test container networking
docker run --rm alpine ping google.com

# Inspect network configuration
docker network ls
docker network inspect bridge

# Use custom networks
docker network create myapp-network
docker run --network myapp-network myapp:latest
```

### Debugging Container Issues
```bash
# Enter container for debugging
docker run -it --entrypoint /bin/sh myapp:latest

# Check container filesystem
docker exec myapp ls -la /app

# Export container for analysis
docker export myapp > container.tar

# Analyze image layers
docker history myapp:latest
```

## Best Practices

- Use `.dockerignore` to exclude unnecessary files
- Leverage OrbStack's Rosetta support for better x86 compatibility
- Set appropriate resource limits for development containers
- Use multi-stage builds to reduce image size
- Regular cleanup with `docker system prune` to manage disk space
- Enable BuildKit for improved build performance and caching