# OrbStack — Docker and Linux Machines on the Mac > Practical guide to OrbStack — the fast, lightweight Docker Desktop alternative for macOS, with Linux machines, Kubernetes and DNS via the orb CLI. Source: https://www.jpkc.com/db/en/cheatsheets/containers/orbstack/ OrbStack is a fast, lightweight macOS app for running Docker containers and full Linux machines – a leaner alternative to Docker Desktop. Instead of a heavy VM, it uses optimized virtualization that barely touches your CPU, RAM and battery and boots in seconds. Through the `orb` (and `orbctl`) CLI you manage machines, open shells, copy files and drive the built-in Kubernetes cluster. Handy: every machine automatically gets a `.orb.local` hostname and a ready-made SSH config. This guide walks you through the `orb` commands you reach for daily – from creating a Linux machine to your Docker and Kubernetes workflow. ## Machine Lifecycle `orb create ` — Create a new Linux machine with the given distro and name. ```bash orb create ubuntu:24.04 myvm ``` `orb create ` — Create a Linux machine with an auto-generated name. ```bash orb create debian:12 ``` `orb start ` — Start a stopped Linux machine. ```bash orb start myvm ``` `orb stop ` — Stop a running Linux machine. ```bash orb stop myvm ``` `orb delete ` — Delete a Linux machine and its data permanently. ```bash orb delete myvm ``` `orb clone ` — Clone an existing Linux machine into a new one. ```bash orb clone myvm myvm-copy ``` `orb rename ` — Rename an existing Linux machine. ```bash orb rename myvm devbox ``` ## Shell & Exec `orb shell` — Open an interactive shell in the default Linux machine. ```bash orb shell ``` `orb shell ` — Open an interactive shell in a specific Linux machine. ```bash orb shell myvm ``` `orb shell -u ` — Open a shell as a specific user in the machine. ```bash orb shell -u root myvm ``` `orb run -- ` — Execute a single command inside a Linux machine. ```bash orb run myvm -- uname -a ``` `orb run -u -- ` — Execute a command as a specific user inside a machine. ```bash orb run -u root myvm -- apt-get update ``` `ssh orb` — SSH into the default machine using OrbStack's built-in SSH config. ```bash ssh orb ``` `ssh @orb` — SSH into a named Linux machine. ```bash ssh myvm@orb ``` ## File Transfer `orb push ` — Copy a file or directory from the host to a Linux machine. ```bash orb push myvm ./app /home/user/app ``` `orb pull ` — Copy a file or directory from a Linux machine to the host. ```bash orb pull myvm /var/log/syslog ./syslog.txt ``` `scp @orb:` — Use standard SCP to copy files to a machine (OrbStack adds SSH config automatically). ```bash scp ./config.yaml myvm@orb:/etc/app/config.yaml ``` `scp @orb: ` — Use standard SCP to copy files from a machine to the host. ```bash scp myvm@orb:/var/log/app.log ./app.log ``` ## Listing & Info `orb list` — List all Linux machines with their status and IP address. ```bash orb list ``` `orb info` — Show detailed info about the default machine (IP, CPU, memory, disk). ```bash orb info ``` `orb info ` — Show detailed information about a specific Linux machine. ```bash orb info myvm ``` `orb version` — Show the installed OrbStack CLI and engine version. ```bash orb version ``` `orb status` — Show the current status of the OrbStack engine (running, stopped, etc.). ```bash orb status ``` ## Docker Integration `docker context ls` — List all Docker contexts. OrbStack registers itself as the 'orbstack' context automatically. ```bash docker context ls ``` `docker context use orbstack` — Switch the active Docker context to OrbStack. ```bash docker context use orbstack ``` `docker run -it ubuntu bash` — Run Docker containers as usual — all standard Docker commands work with OrbStack. ```bash docker run -it ubuntu bash ``` `docker compose up -d` — Use Docker Compose normally — OrbStack is fully Docker-compatible. ```bash docker compose up -d ``` `docker system df` — Show OrbStack's Docker disk usage: images, containers, volumes, and build cache. ```bash docker system df ``` `docker buildx build --platform linux/amd64,linux/arm64 -t name .` — Multi-platform builds work out of the box with OrbStack's bundled buildx. ```bash docker buildx build --platform linux/amd64,linux/arm64 -t my-app . ``` ## Kubernetes `orbctl k8s start` — Start the built-in single-node Kubernetes cluster. ```bash orbctl k8s start ``` `orbctl k8s stop` — Stop the Kubernetes cluster without deleting data. ```bash orbctl k8s stop ``` `orbctl k8s reset` — Reset the Kubernetes cluster to a clean state (destroys all workloads). ```bash orbctl k8s reset ``` `kubectl config use-context orbstack` — Switch kubectl to use the OrbStack Kubernetes cluster. ```bash kubectl config use-context orbstack ``` `kubectl get nodes` — Verify the OrbStack Kubernetes node is ready. ```bash kubectl get nodes ``` `kubectl get pods -A` — List all pods across all namespaces in the OrbStack k8s cluster. ```bash kubectl get pods -A ``` ## Configuration & Updates `orb config` — Show the current OrbStack configuration. ```bash orb config ``` `orb config set ` — Set a configuration option for OrbStack. ```bash orb config set defaultMachine myvm ``` `orbctl update` — Check for and apply OrbStack updates. ```bash orbctl update ``` `orbctl restart` — Restart the OrbStack engine (useful after config changes or if the engine hangs). ```bash orbctl restart ``` `orbctl stop` — Fully stop the OrbStack engine and all machines. ```bash orbctl stop ``` ## Networking & DNS `ping myvm.orb.local` — Every OrbStack machine gets a .orb.local hostname resolvable from macOS. ```bash ping myvm.orb.local ``` `curl http://myvm.orb.local:8080` — Access services running inside a Linux machine by hostname without port mapping. ```bash curl http://myvm.orb.local:8080 ``` `curl http://host.internal` — Access the macOS host from inside a Linux machine or container using this special hostname. ```bash curl http://host.internal:3000 ``` `orb info ` — Look up a machine's IP address to use for direct connections. ```bash orb info myvm ``` ## Available Linux Distros `orb create ubuntu ` — Create an Ubuntu machine (latest LTS by default). ```bash orb create ubuntu devbox ``` `orb create ubuntu:24.04 ` — Create an Ubuntu 24.04 (Noble) machine. ```bash orb create ubuntu:24.04 noble ``` `orb create debian:12 ` — Create a Debian 12 (Bookworm) machine. ```bash orb create debian:12 bookworm ``` `orb create fedora ` — Create a Fedora Linux machine. ```bash orb create fedora fedora-dev ``` `orb create arch ` — Create an Arch Linux machine. ```bash orb create arch arch-dev ``` `orb create alpine ` — Create a minimal Alpine Linux machine. ```bash orb create alpine tiny ``` `orb create nixos ` — Create a NixOS machine. ```bash orb create nixos nix-dev ``` ## Conclusion OrbStack shows how much smoother container-based development on the Mac can be: fast startup, a light resource footprint and a seamless switch between Docker, full Linux machines and Kubernetes – all from a single CLI. If you currently rely on Docker Desktop, the move pays off above all for noticeably better battery life and the automatic `.orb.local` hostnames. Keep in mind that OrbStack runs on macOS only and requires a license for commercial use – it is free for personal use. ## Further Reading - [OrbStack – official documentation](https://docs.orbstack.dev/) – manual and CLI reference - [OrbStack – project site](https://orbstack.dev/) – feature overview and download ## Related Commands - [ddev](https://www.jpkc.com/db/en/cheatsheets/containers/ddev/) – container-based local dev environments for PHP and more - [docker](https://www.jpkc.com/db/en/cheatsheets/containers/docker/) – build, run and manage containers - [docker-compose](https://www.jpkc.com/db/en/cheatsheets/containers/docker-compose/) – define multi-container setups declaratively