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
Decision gist · record as of 2026-06-24
OrbStack Best Practices teaches orbctl commands and workflows for running Linux VMs and Docker efficiently on macOS. 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.
Use it when
- OrbStack commands for VM management include `orbctl create` (provision a new machine), `orbctl start` (boot the VM).
- OrbStack networking eliminates traditional port mapping through automatic localhost access and zero-config HTTPS domains.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
alleneubank/claude-code/orbstack-best-practices · repository language: Zig
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
File tree — 1 file
.claude/skills/orbstack-best-practices/SKILL.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Learn OrbStack commands and workflows for managing Linux VMs and Docker on macOS”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
OrbStack CLI is the command reference and recipe book for driving OrbStack—a Docker and Linux VM runtime for macOS—from the terminal. It covers the orb and orbctl commands for machine lifecycle management, file transfer, Docker operations, container domains, networking, and CI automation.
Troubleshoot Docker Hub connectivity problems in OrbStack by identifying whether failures stem from network routing, system proxy settings, or daemon configuration. The skill guides you through diagnostic checks, proxy setup, and daemon tuning to restore reliable image pulls.
Tunnel Doctor isolates and resolves conflicts when Tailscale coexists with proxy/VPN tools like Shadowrocket, Clash, or Surge on macOS. It addresses route table corruption, environment variable misconfigurations, system proxy bypass issues, SSH double-tunneling, and VM/container proxy propagation problems—covering scenarios from browser 503 errors to Docker timeouts and WSL SSH access.
k8s-vind lets you provision and operate virtual Kubernetes clusters as isolated workloads inside a host cluster. Use it to spin up ephemeral dev environments, establish tenant isolation, or test configurations without overhead. The skill exposes 14 tools for cluster creation, lifecycle management, connection handling, and resource optimization.
k8s-deploy provides deployment workflows for Kubernetes using kubectl-mcp-server tools, supporting standard deployments via manifests or Helm alongside progressive delivery through Argo Rollouts and Flagger. It covers canary promotions, blue-green strategies, rolling updates, scaling, and rollback operations across single and multi-cluster environments.
This skill provides a comprehensive foundation for fullstack development, bundling essential configurations, workflows, and architectural patterns across multiple domains. It accelerates project initialization by consolidating best practices and proven setups, letting you focus on building rather than scaffolding infrastructure.