OrbStack Best Practices
OrbStack is a fast, lightweight Docker and Linux VM runtime for macOS. Replaces Docker Desktop with better performance and seamless macOS integration.
Core Commands
Start/stop
orb # Start + open default machine shell orb start # Start OrbStack orb stop # Stop OrbStack
Machine management
orb list # List machines orb create ubuntu # Create with latest version orb create ubuntu:jammy myvm # Specific version + name orb create --arch amd64 ubuntu intel # x86 on Apple Silicon orb delete myvm # Delete machine
Shell access
orb # Default machine shell orb -m myvm # Specific machine orb -u root # As root orb -m myvm -u root # Combined
Run commands
orb uname -a # Run in default machine orb -m myvm ./script.sh # Run in specific machine
File transfer
orb push ~/local.txt # Copy to Linux orb pull ~/remote.txt # Copy from Linux orb push -m vm ~/f.txt /dest/ # Push to specific machine/path
Docker/K8s
orb restart docker # Restart Docker engine orb logs docker # Docker engine logs orb start k8s # Start Kubernetes orb delete k8s # Delete K8s cluster
Config
orb config set memory_mib 8192 # Set memory limit orb config docker # Edit daemon.json
Key Paths
Path Description
~/OrbStack/<machine>/
Linux files from macOS
~/OrbStack/docker/volumes/
Docker volumes from macOS
/mnt/mac/Users/...
macOS files from Linux
/mnt/machines/<name>/
Other machines from Linux
~/.orbstack/ssh/id_ed25519
SSH private key
~/.orbstack/config/docker.json
Docker daemon config
DNS Names
Pattern Description
<machine>.orb.local
Linux machine
<container>.orb.local
Docker container
<svc>.<project>.orb.local
Compose service
host.orb.internal
macOS from Linux machine
host.docker.internal
macOS from container
docker.orb.internal
Docker from Linux machine
Machine Lifecycle
Creation
orb create ubuntu # Latest Ubuntu orb create ubuntu:noble devbox # Ubuntu 24.04 named "devbox" orb create --arch amd64 debian x86vm # x86 emulation via Rosetta orb create --set-password ubuntu pwvm # With password set orb create ubuntu myvm -c cloud.yml # With cloud-init
Supported distros: Alma, Alpine, Arch, CentOS, Debian, Devuan, Fedora, Gentoo, Kali, NixOS, openSUSE, Oracle, Rocky, Ubuntu, Void
Lifecycle
orb start myvm # Start stopped machine orb stop myvm # Stop machine orb restart myvm # Restart orb delete myvm # Delete permanently orb default myvm # Set as default machine orb logs myvm # View boot logs
Cloud-Init
Create machines with automated provisioning:
orb create ubuntu myvm -c user-data.yml
Example user-data.yml :
#cloud-config packages:
- git
- vim
- docker.io
users:
- name: dev groups: sudo, docker shell: /bin/bash sudo: ALL=(ALL) NOPASSWD:ALL
runcmd:
- systemctl enable docker
- systemctl start docker
Debug cloud-init:
orb logs myvm # Boot logs from macOS orb -m myvm cloud-init status --long # Status inside machine orb -m myvm cat /var/log/cloud-init-output.log
Networking
Port Access
Servers in Linux machines are automatically on localhost :
In Linux: python3 -m http.server 8000
From macOS: curl localhost:8000 or curl myvm.orb.local:8000
Connecting from Linux to macOS
From Linux machine
curl host.orb.internal:3000
From Docker container
curl host.docker.internal:3000
VPN/Proxy
-
Fully VPN-compatible with automatic DNS handling
-
Follows macOS proxy settings automatically
-
Custom proxy: orb config set network_proxy http://proxy:8080
-
Disable: orb config set network_proxy none
File Sharing
macOS Files from Linux
Same paths work
cat /Users/allen/file.txt cat /mnt/mac/Users/allen/file.txt # Explicit prefix
Linux Files from macOS
ls ~/OrbStack/myvm/home/user/ ls ~/OrbStack/docker/volumes/myvolume/
Transfer Commands
orb push ~/local.txt # To default machine home orb pull ~/remote.txt # From default machine orb push -m vm ~/f.txt /tmp/ # To specific path
SSH Access
Built-in multiplexed SSH server (no per-machine setup):
ssh orb # Default machine ssh myvm@orb # Specific machine ssh user@myvm@orb # Specific user + machine
IDE Setup
VS Code: Install "Remote - SSH" extension, connect to orb or myvm@orb
JetBrains: Host localhost , Port 32222 , Key ~/.orbstack/ssh/id_ed25519
Ansible
[servers] myvm@orb ansible_user=ubuntu
SSH agent forwarding is automatic.
Docker Integration
Container Domains
docker run --name web nginx
Access: http://web.orb.local (no port needed for web servers)
Compose: <service>.<project>.orb.local
HTTPS
Zero-config HTTPS for all .orb.local domains:
curl https://mycontainer.orb.local
Custom Domains
docker run -l dev.orbstack.domains=myapp.local nginx
Host Networking
docker run --net=host nginx
localhost works both directions
x86 Emulation
docker run --platform linux/amd64 ubuntu export DOCKER_DEFAULT_PLATFORM=linux/amd64 # Default to x86
SSH Agent in Containers
docker run -v /run/host-services/ssh-auth.sock:/agent.sock
-e SSH_AUTH_SOCK=/agent.sock alpine
Volumes vs Bind Mounts
Prefer volumes for performance (data stays in Linux):
docker run -v mydata:/data alpine # Volume (fast) docker run -v ~/code:/code alpine # Bind mount (slower)
Kubernetes
orb start k8s # Start cluster kubectl get nodes # kubectl included
All service types accessible from macOS without port-forward:
curl myservice.default.svc.cluster.local # cluster.local works curl 192.168.194.20 # Pod IPs work curl myservice.k8s.orb.local # LoadBalancer wildcard
Local images available immediately (use non-latest tag or imagePullPolicy: IfNotPresent ).
Troubleshooting
orb report # Generate diagnostic report orb logs myvm # Machine boot logs orb logs docker # Docker engine logs orb restart docker # Restart Docker orb reset # Factory reset (deletes everything)
Cannot connect to Docker daemon: Start OrbStack with orb start , or fix context with docker context use orbstack
Machine not starting: Check orb logs myvm , try orb restart myvm
Rosetta x86 error: Install x86 libc:
sudo dpkg --add-architecture amd64 sudo apt update && sudo apt install libc6:amd64
Configuration
orb config set rosetta true # Enable x86 emulation orb config set memory_mib 8192 # Memory limit (MiB) orb config set cpu 4 # CPU limit (cores) orb config set network_proxy auto # Proxy (auto/none/url)
Docker daemon config at ~/.orbstack/config/docker.json :
{ "insecure-registries": ["registry.local:5000"], "registry-mirrors": ["https://mirror.gcr.io"] }
Apply with orb restart docker .
macOS Commands from Linux
mac open https://example.com # Open URL in macOS browser mac uname -a # Run macOS command mac link brew # Link command for reuse mac notify "Build done" # Send notification
Forward env vars:
ORBENV=AWS_PROFILE:EDITOR orb ./deploy.sh