OrbStack — Docker and Linux Machines on the Mac

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 <distro> <name> — Create a new Linux machine with the given distro and name.

orb create ubuntu:24.04 myvm

orb create <distro> — Create a Linux machine with an auto-generated name.

orb create debian:12

orb start <name> — Start a stopped Linux machine.

orb start myvm

orb stop <name> — Stop a running Linux machine.

orb stop myvm

orb delete <name> — Delete a Linux machine and its data permanently.

orb delete myvm

orb clone <source> <target> — Clone an existing Linux machine into a new one.

orb clone myvm myvm-copy

orb rename <old> <new> — Rename an existing Linux machine.

orb rename myvm devbox

Shell & Exec

orb shell — Open an interactive shell in the default Linux machine.

orb shell

orb shell <name> — Open an interactive shell in a specific Linux machine.

orb shell myvm

orb shell -u <user> <name> — Open a shell as a specific user in the machine.

orb shell -u root myvm

orb run <name> -- <command> — Execute a single command inside a Linux machine.

orb run myvm -- uname -a

orb run -u <user> <name> -- <command> — Execute a command as a specific user inside a machine.

orb run -u root myvm -- apt-get update

ssh orb — SSH into the default machine using OrbStack's built-in SSH config.

ssh orb

ssh <name>@orb — SSH into a named Linux machine.

ssh myvm@orb

File Transfer

orb push <name> <local_path> <remote_path> — Copy a file or directory from the host to a Linux machine.

orb push myvm ./app /home/user/app

orb pull <name> <remote_path> <local_path> — Copy a file or directory from a Linux machine to the host.

orb pull myvm /var/log/syslog ./syslog.txt

scp <local> <name>@orb:<remote> — Use standard SCP to copy files to a machine (OrbStack adds SSH config automatically).

scp ./config.yaml myvm@orb:/etc/app/config.yaml

scp <name>@orb:<remote> <local> — Use standard SCP to copy files from a machine to the host.

scp myvm@orb:/var/log/app.log ./app.log

Listing & Info

orb list — List all Linux machines with their status and IP address.

orb list

orb info — Show detailed info about the default machine (IP, CPU, memory, disk).

orb info

orb info <name> — Show detailed information about a specific Linux machine.

orb info myvm

orb version — Show the installed OrbStack CLI and engine version.

orb version

orb status — Show the current status of the OrbStack engine (running, stopped, etc.).

orb status

Docker Integration

docker context ls — List all Docker contexts. OrbStack registers itself as the 'orbstack' context automatically.

docker context ls

docker context use orbstack — Switch the active Docker context to OrbStack.

docker context use orbstack

docker run -it ubuntu bash — Run Docker containers as usual — all standard Docker commands work with OrbStack.

docker run -it ubuntu bash

docker compose up -d — Use Docker Compose normally — OrbStack is fully Docker-compatible.

docker compose up -d

docker system df — Show OrbStack's Docker disk usage: images, containers, volumes, and build cache.

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.

docker buildx build --platform linux/amd64,linux/arm64 -t my-app .

Kubernetes

orbctl k8s start — Start the built-in single-node Kubernetes cluster.

orbctl k8s start

orbctl k8s stop — Stop the Kubernetes cluster without deleting data.

orbctl k8s stop

orbctl k8s reset — Reset the Kubernetes cluster to a clean state (destroys all workloads).

orbctl k8s reset

kubectl config use-context orbstack — Switch kubectl to use the OrbStack Kubernetes cluster.

kubectl config use-context orbstack

kubectl get nodes — Verify the OrbStack Kubernetes node is ready.

kubectl get nodes

kubectl get pods -A — List all pods across all namespaces in the OrbStack k8s cluster.

kubectl get pods -A

Configuration & Updates

orb config — Show the current OrbStack configuration.

orb config

orb config set <key> <value> — Set a configuration option for OrbStack.

orb config set defaultMachine myvm

orbctl update — Check for and apply OrbStack updates.

orbctl update

orbctl restart — Restart the OrbStack engine (useful after config changes or if the engine hangs).

orbctl restart

orbctl stop — Fully stop the OrbStack engine and all machines.

orbctl stop

Networking & DNS

ping myvm.orb.local — Every OrbStack machine gets a .orb.local hostname resolvable from macOS.

ping myvm.orb.local

curl http://myvm.orb.local:8080 — Access services running inside a Linux machine by hostname without port mapping.

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.

curl http://host.internal:3000

orb info <name> — Look up a machine's IP address to use for direct connections.

orb info myvm

Available Linux Distros

orb create ubuntu <name> — Create an Ubuntu machine (latest LTS by default).

orb create ubuntu devbox

orb create ubuntu:24.04 <name> — Create an Ubuntu 24.04 (Noble) machine.

orb create ubuntu:24.04 noble

orb create debian:12 <name> — Create a Debian 12 (Bookworm) machine.

orb create debian:12 bookworm

orb create fedora <name> — Create a Fedora Linux machine.

orb create fedora fedora-dev

orb create arch <name> — Create an Arch Linux machine.

orb create arch arch-dev

orb create alpine <name> — Create a minimal Alpine Linux machine.

orb create alpine tiny

orb create nixos <name> — Create a NixOS machine.

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.