orbstack-best-practices

OrbStack のベストプラクティス

OrbStack は、macOS 向けの高速な Docker および Linux VM ランタイムです。Docker Desktop を置き換え、パフォーマンスを向上させ、macOS とシームレスに統合します。

基本コマンド

# 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

主なパス

場所	パス
macOS から Linux のファイルにアクセス	~/OrbStack/<machine>/
macOS から Docker ボリュームにアクセス	~/OrbStack/docker/volumes/
Linux から macOS のファイルにアクセス	/mnt/mac/Users/...（同じパスからも直接アクセス可能）
Linux から他のマシンにアクセス	/mnt/machines/<name>/
SSH キー	~/.orbstack/ssh/id_ed25519
Docker デーモンの設定	~/.orbstack/config/docker.json

ネットワーク（OrbStack 固有）

Linux マシン内のサーバーは、ポートマッピングなしで macOS の localhost から自動的に利用できます。

DNS 名：

パターン	解決先
<machine>.orb.local	Linux VM
<container>.orb.local	Docker コンテナ
<svc>.<project>.orb.local	Compose サービス
host.orb.internal	macOS ホスト（Linux マシンから）
host.docker.internal	macOS ホスト（コンテナから）

すべての .orb.local ドメインで、ゼロコンフィグ HTTPS が自動的に利用できます。

コンテナのカスタムドメイン：docker run -l dev.orbstack.domains=myapp.local nginx

VPN に対応しており、macOS のプロキシ設定が自動的に適用されます。

SSH アクセス

単一の多重化 SSH サーバーを使用するため、マシンごとの設定は不要です。

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

IDE の設定：VS Code の「Remote - SSH」で orb または myvm@orb を指定します。JetBrains の場合は、ホストに localhost、ポートに 32222、キーに ~/.orbstack/ssh/id_ed25519 を指定します。SSH エージェントの転送は自動的に行われます。

Docker Desktop との違い

• コンテナのドメインはポートマッピングなしで解決されます（localhost:8080 ではなく web.orb.local）。
• バインドマウントより名前付きボリュームを優先してください。データは Linux 内に保持され、ファイルシステムをまたぐことによるオーバーヘッドがありません。
• Apple Silicon で x86 イメージを使う場合：docker run --platform linux/amd64 ubuntu または export DOCKER_DEFAULT_PLATFORM=linux/amd64。
• コンテナ内の SSH エージェント：-v /run/host-services/ssh-auth.sock:/agent.sock -e SSH_AUTH_SOCK=/agent.sock。
• Kubernetes：kubectl port-forward を使わずに、すべてのサービスタイプに macOS からアクセスできます。cluster.local DNS もそのまま機能します。

Linux から macOS のコマンドを実行

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

トラブルシューティング

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 エラー：sudo dpkg --add-architecture amd64 && sudo apt install libc6:amd64

Cloud-init のデバッグ：orb -m myvm cloud-init status --long または orb -m myvm cat /var/log/cloud-init-output.log