orbstack-best-practices
Learn essential orbctl commands for creating and managing Linux virtual machines, running Docker containers, and transferring files on macOS. Discover OrbStack's networking model with automatic localhost access and zero-config HTTPS domains, plus SSH integration for IDE remote development. Includes troubleshooting tips and macOS-to-Linux interop.
OrbStack Best Practices teaches orbctl commands and workflows for running Linux VMs and Docker efficiently on macOS.
AI-generated summary based on this skill's SKILL.md
Install
alleneubank/claude-code/orbstack-best-practices · repository language: Zig
git clone https://github.com/alleneubank/claude-code
cp -r claude-code/.claude/skills/orbstack-best-practices ~/.claude/skills/orbstack-best-practicesnpx skillfed install alleneubank/claude-code/orbstack-best-practicesFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I use OrbStack to run Docker on macOS?
OrbStack best practices for macOS Docker use starts with understanding that OrbStack manages a lightweight Linux VM transparently. Use `orbctl` commands to create machines, then run `docker` commands as normal—OrbStack intercepts them and executes containers in its managed VM. Key commands: `orbctl create` to set up a machine, `orbctl start` to boot it, and `docker ps` to list running containers. OrbStack integrates seamlessly with your macOS Docker CLI, eliminating the overhead of Docker Desktop while maintaining full compatibility.
What orbstack commands are essential for managing Linux VMs?
OrbStack commands for VM management include `orbctl create` (provision a new machine), `orbctl start` (boot the VM), `orbctl stop` (shut down), `orbctl remove` (delete), and `orbctl list` (view all machines). For SSH access, use `orbctl shell` to open a terminal session. File transfer between Mac and Linux uses `orbctl transfer` or standard `scp`. Machine lifecycle is controlled entirely through `orbctl`, making it straightforward to manage multiple VMs and switch between them without manual configuration.
How does OrbStack networking work without port mapping?
OrbStack networking eliminates traditional port mapping through automatic localhost access and zero-config HTTPS domains. Containers are accessible directly via `localhost:<port>` from macOS without explicit mapping. OrbStack also provides `.orb.local` domains for services—use `orbctl domain` to register them. This networking model simplifies development workflows: services running in containers appear as if they're on your Mac, and IDE remote development tools connect via SSH without complex port forwarding setup.
How do I set up SSH access and IDE remote development with OrbStack?
OrbStack SSH setup begins with `orbctl shell` to access the Linux VM directly, or configure SSH keys for remote IDE integration. Most IDEs (VS Code, JetBrains) support SSH remote development—point them to OrbStack's VM using the hostname provided by `orbctl info`. OrbStack handles SSH authentication automatically. Once configured, your IDE runs on macOS but executes code and debugging in the OrbStack VM, giving you full Linux development environment access without leaving your Mac workflow.
What are key differences between OrbStack and Docker Desktop?
OrbStack best practices versus Docker Desktop: OrbStack uses a more efficient VM architecture with better macOS integration, lower resource overhead, and native support for both Docker and Kubernetes. Unlike Docker Desktop, OrbStack provides automatic localhost networking without port mapping, zero-config `.orb.local` HTTPS domains, and transparent file transfer. OrbStack also includes Rosetta x86 emulation support and cloud-init configuration for advanced VM setup, making it ideal for teams prioritizing performance and developer experience on macOS.
How do I troubleshoot OrbStack issues and optimize performance?
OrbStack troubleshooting starts with `orbctl status` to check VM health and `orbctl logs` for error messages. Performance optimization includes: allocating sufficient CPU/memory via `orbctl config`, using cloud-init for efficient machine provisioning, and managing Docker volumes with `docker volume` commands. For file transfer slowness, verify network connectivity with `orbctl shell` then `ping`. Common issues resolve by restarting the VM (`orbctl stop && orbctl start`). Check OrbStack's documentation for Rosetta emulation settings if running x86 containers on Apple Silicon.
SKILL.md
rendered from the published skill — quoted content, verbatim
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
```bash
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
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
.claude/skills/orbstack-best-practices/SKILL.md