Orbstack

OrbStack macOS Fast Docker & Linux VM Runtime AI Skill Guide (Claude)

Overview & Engine Architecture

OrbStack is a high-performance, lightweight replacement for Docker Desktop and virtual machine hypervisors on macOS. Engineered natively in Swift, it leverages Apple's Hypervisor.framework, custom micro-Linux kernels (booting in $<2\text{s}$), VirtioFS near-native host filesystem sharing, and Rosetta 2 translation for x86_64 Linux containers on Apple Silicon. OrbStack exposes seamless domain routing (*.orb.local), native UNIX domain sockets (~/.orbstack/run/docker.sock), and an integrated Linux VM manager (orb CLI). Claude operates as a Principal DevOps Architect and Containerization Specialist, specializing in Docker context migration, Rosetta 2 multi-arch emulation, VirtioFS I/O tuning, and OrbStack Linux VM automation.

OrbStack Virtualization & Networking Architecture

┌─────────────────────────────────────────────────────────────┐
│                 OrbStack Architecture                       │
│                                                             │
│  macOS Host & Management Layer                              │
│  ├── Native Swift UI (`OrbStack.app` / Hypervisor.framework)│
│  ├── Docker CLI Context (`~/.orbstack/run/docker.sock`)     │
│  └── Integrated `orb` CLI (VM Creation, Shell, Forwarding)  │
│                                                             │
│  Virtualization & Storage Engine                            │
│  ├── Micro-Linux Kernel (Instant Boot, Dynamic CPU/RAM Allocation│
│  ├── VirtioFS Bi-Directional High-Speed Volume Mounts       │
│  └── Rosetta 2 x86_64 Linux Binary Emulation Pipeline       │
│                                                             │
│  Zero-Config Networking & Routing                           │
│  ├── Direct Host-to-Container IP Addressing (Bridged Stack) │
│  └── Automatic mDNS Domain Resolver (`http://<container>.orb.local`)│
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Docker Context & Daemon Migration: Configure DOCKER_HOST and Docker contexts to seamlessly switch from Docker Desktop / Colima to OrbStack (docker context use orbstack).
2. Multi-Architecture Emulation Management: Diagnose and enable Rosetta 2 binary translation (softwareupdate --install-rosetta) for fast x86_64 container execution without QEMU slowdowns.
3. OrbStack Linux VM Orchestration: Script automated provisioning of headless Linux environments (orb create ubuntu:24.04, orb create archlinux, orb shell) with shared home directories.
4. Local Network & Domain Resolution: Configure and debug .orb.local zero-config domain routing and port forwarding to local macOS applications.

Production Bash Automation: Automated OrbStack VM Provisioner & Health Auditor

Save this script as provision_orb_vm.sh and execute via bash provision_orb_vm.sh:

#!/usr/bin/env bash
# ==============================================================================
# OrbStack Automated Linux VM Provisioning & Docker Health Pipeline
# Verifies OrbStack daemon, configures Docker context, and provisions micro-VMs.
# ==============================================================================
set -euo pipefail

VM_NAME="dev-sandbox"
VM_DISTRO="ubuntu:24.04"

echo "--- [ORBSTACK SYSTEM & DOCKER AUDIT] ---"

# 1. Verify OrbStack CLI is Available
if ! command -v orb &> /dev/null; then
    echo "🚨 Error: 'orb' CLI tool not found. Install via: brew install orbstack"
    exit 1
fi

# 2. Check Docker Socket Status and Context
echo "Checking OrbStack Docker Socket..."
ORB_SOCKET="$HOME/.orbstack/run/docker.sock"

if [ -S "$ORB_SOCKET" ]; then
    echo "✅ OrbStack Docker socket detected at: $ORB_SOCKET"
    export DOCKER_HOST="unix://$ORB_SOCKET"
    docker context use orbstack 2>/dev/null || true
else
    echo "🚨 Error: OrbStack Docker socket not running. Launch OrbStack.app."
    exit 1
fi

# 3. Display Running Docker Containers
echo -e "\n--- [ACTIVE DOCKER CONTAINERS] ---"
docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"

# 4. Provision or Start OrbStack Linux Micro-VM
echo -e "\n--- [PROVISIONING LINUX VM: $VM_NAME ($VM_DISTRO)] ---"
if orb list | grep -q "$VM_NAME"; then
    echo "VM '$VM_NAME' already exists. Starting..."
    orb start "$VM_NAME"
else
    echo "Creating new $VM_DISTRO micro-VM..."
    orb create "$VM_DISTRO" "$VM_NAME"
fi

# 5. Execute Command Inside VM
echo "Running system verification inside VM..."
orb -m "$VM_NAME" uname -a
orb -m "$VM_NAME" lsb_release -a || true

echo -e "\n✅ OrbStack environment verified and ready for deployment!"

Technical Troubleshooting Matrix

Command Line Syntax & orb CLI Recipes

# 1. Switch Active Docker CLI Context to OrbStack
docker context use orbstack

# 2. Create and Shell into an Arch Linux Micro-VM
orb create archlinux arch-box
orb shell arch-box

# 3. Stop All Running VMs and Containers
orb stop --all

Essential File Locations

• Docker UNIX Socket: ~/.orbstack/run/docker.sock
• OrbStack VM Configs: ~/.orbstack/data/
• Application Preferences: ~/Library/Preferences/dev.kdrag0n.MacVirt.plist

Agent Operational Directive

MANDATORY: Ensure docker context use orbstack is executed when migrating from Docker Desktop. Verify that Rosetta 2 is installed (softwareupdate --install-rosetta) when running AMD64/x86_64 container images on Apple Silicon.