Orbstack Best Practices

Name: Orbstack Best Practices
Author: 0xbigboss

0xbigboss/claude-code

246 installs
52 repo stars
Updated June 24, 2026
0xbigboss/claude-code

Run and debug containerized local stacks on macOS with OrbStack when agents dockerize apps, compose microservices, or troubleshoot dev networking, volumes, and resource limits.

About

Covers OrbStack best practices for fast macOS container development including Docker workflows, local Kubernetes clusters, networking, volume strategies, and performance tuning so agents dockerize stacks efficiently.

Docker on Mac
fast startup
local Kubernetes
networking
resource limits

Orbstack Best Practices by the numbers

246 all-time installs (skills.sh)
Ranked #365 of 1,435 DevOps & CI/CD skills by installs in the Skillselion catalog
Data as of Jul 30, 2026 (Skillselion catalog sync)

npx skills add https://github.com/0xbigboss/claude-code --skill orbstack-best-practices

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/0xbigboss/claude-code/orbstack-best-practices.svg)](https://skillselion.com/skills/0xbigboss/claude-code/orbstack-best-practices)

Installs	246
repo stars	★ 52
Last updated	June 24, 2026
Repository	0xbigboss/claude-code ↗

What it does

Run and debug containerized local stacks on macOS with OrbStack when agents dockerize apps, compose microservices, or troubleshoot dev networking, volumes, and resource limits.

Files

SKILL.mdMarkdownGitHub ↗

OrbStack Best Practices

OrbStack is a fast Docker and Linux VM runtime for macOS. Replaces Docker Desktop with better performance and seamless macOS integration.

Core Commands

# Machine lifecycle
orb list                               # List machines
orb create ubuntu:noble myvm           # Create (distro:version name)
orb create --arch amd64 ubuntu x86vm  # x86 emulation via Rosetta
orb create ubuntu myvm -c cloud.yml   # With cloud-init
orb start/stop/restart/delete myvm
orb default myvm                       # Set default machine

# Shell and exec
orb                           # Shell into default machine
orb -m myvm -u root           # Specific machine + user
orb -m myvm ./script.sh       # Run command in machine

# File transfer
orb push ~/local.txt          # Copy to default machine home
orb pull ~/remote.txt         # Copy from default machine
orb push -m vm ~/f.txt /tmp/  # Specific machine + path

# Docker/K8s
orb restart docker            # Restart Docker engine
orb logs docker               # Docker engine logs
orb start k8s / orb delete k8s

# Config
orb config set memory_mib 8192
orb config set cpu 4
orb config set rosetta true
orb config set network_proxy http://proxy:8080

Key Paths

Location	Path
Linux files from macOS	`~/OrbStack/<machine>/`
Docker volumes from macOS	`~/OrbStack/docker/volumes/`
macOS files from Linux	`/mnt/mac/Users/...` (also at same path directly)
Other machines from Linux	`/mnt/machines/<name>/`
SSH key	`~/.orbstack/ssh/id_ed25519`
Docker daemon config	`~/.orbstack/config/docker.json`

Networking (OrbStack-Specific)

Servers in Linux machines are automatically available on `localhost` on macOS — no port mapping required.

DNS names:

Pattern	Resolves to
`<machine>.orb.local`	Linux VM
`<container>.orb.local`	Docker container
`<svc>.<project>.orb.local`	Compose service
`host.orb.internal`	macOS host (from Linux machine)
`host.docker.internal`	macOS host (from container)

All .orb.local domains get zero-config HTTPS automatically.

Custom container domain: docker run -l dev.orbstack.domains=myapp.local nginx

VPN-compatible; follows macOS proxy settings automatically.

SSH Access

Single multiplexed SSH server — no per-machine setup needed:

ssh orb                    # Default machine
ssh myvm@orb               # Specific machine
ssh user@myvm@orb          # Specific user + machine

IDE config: VS Code "Remote - SSH" → orb or myvm@orb. JetBrains: host localhost, port 32222, key ~/.orbstack/ssh/id_ed25519. SSH agent forwarding is automatic.

Docker Differences from Docker Desktop

Container domains resolve without port mapping (web.orb.local instead of localhost:8080).
Prefer named volumes over bind mounts — data stays in Linux, no cross-filesystem overhead.
x86 images on Apple Silicon: docker run --platform linux/amd64 ubuntu or export DOCKER_DEFAULT_PLATFORM=linux/amd64.
SSH agent in containers: -v /run/host-services/ssh-auth.sock:/agent.sock -e SSH_AUTH_SOCK=/agent.sock.
Kubernetes: all service types accessible from macOS without kubectl port-forward; cluster.local DNS works directly.

macOS Commands from Linux

mac open https://example.com   # Open in macOS browser
mac notify "Build done"        # macOS notification
ORBENV=AWS_PROFILE:EDITOR orb ./deploy.sh  # Forward env vars

Troubleshooting

orb report              # Generate diagnostic report
orb logs myvm           # Machine boot logs
orb restart docker      # Restart Docker engine
orb reset               # Factory reset (deletes everything)
docker context use orbstack  # Fix "cannot connect to Docker daemon"

Rosetta x86 error: sudo dpkg --add-architecture amd64 && sudo apt install libc6:amd64

Cloud-init debug: orb -m myvm cloud-init status --long or orb -m myvm cat /var/log/cloud-init-output.log