orbstack-best-practices

Patterns for OrbStack Linux VMs and Docker on macOS. Covers orbctl/orb commands, machine lifecycle, cloud-init, networking, file sharing, and SSH access. Must use when working with OrbStack, orbctl commands, or Linux VMs on macOS.

2.10x

Quality

89%

Does it follow best practices?

Impact

99%

2.10x

Average score across 3 eval scenarios

Securityby

Advisory

Suggest reviewing before use

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

Repository: NeverSight/skills_feed
Commit: 5342bca

Last updated: about 5 hours ago
Created: about 5 hours ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.