OrbStack CLI

OrbStack is a fast Docker + Linux VM runtime for macOS (a Docker Desktop replacement). You drive it from the terminal with four commands. This skill is the command index and recipe book; read the matching references/ file when you need full flags or detail.

Which command do I use?

Command	Use it for
`orb` (no args)	Open a shell in the default Linux machine
`orb <cmd> [args]`	Run `<cmd>` inside the default Linux machine (e.g. `orb uname -a`)
`orb <subcommand>` / `orbctl <subcommand>`	Manage OrbStack and its machines (create, start, config, logs...)
`docker` / `docker compose` / `kubectl`	Build/run containers and Kubernetes - run these straight from macOS, no VM needed
`mac <cmd>`	Run a macOS command from inside a Linux machine (e.g. `mac open`, `mac notify`)

orb and orbctl are the same binary: orb foo runs foo in Linux, but orb create/orb start/etc. (any known subcommand) manage OrbStack. When a name could collide, prefer orbctl <subcommand> to be explicit.

Cheat sheet (most common)

# Machines
orb create ubuntu                       # newest Ubuntu, VM named "ubuntu"
orb create ubuntu:24.04 dev             # specific version + name
orb list                                # list machines + status
orb                                     # shell into default machine
orb -m dev -u root apt update           # run a command in "dev" as root
orb push ~/file.txt code/               # copy Mac -> Linux (~/code/)
orb pull code/out.log .                 # copy Linux -> Mac
orb stop dev / orb start dev / orb delete dev

# Docker (just use docker; OrbStack is the "orbstack" context)
docker run -p 80:80 nginx               # then visit http://localhost
docker run -l dev.orbstack.domains=app.local nginx   # custom domain

# Kubernetes
orb start k8s && kubectl get pods -A

# Service control / health
orb status                              # Running=0, Stopped=1, Starting=2
orb doctor --fix                        # verify + repair Docker integration
orb restart docker                      # restart just the Docker engine

# Config (see `orb config show` for all keys)
orb config set memory_mib 8192
orb config set cpu 4

Key facts you can rely on

Auto port-forwarding: a server listening inside a container or VM is reachable on the same port on macOS localhost - no -p needed for VMs, and containers are also reachable by domain without any mapping.
Domains: every container is at <name>.orb.local; compose services at <svc>.<project>.orb.local; VMs at <machine>.orb.local. All get zero-config HTTPS. Visit https://orb.local for an index of running containers. → references/domains.md
Docker context is named orbstack and is selected automatically. If docker says "cannot connect to the daemon": docker context use orbstack or orb doctor --fix. → references/docker.md
File paths: Linux files from macOS at ~/OrbStack/<machine>/; macOS files from Linux at /mnt/mac/...; Docker volumes at ~/OrbStack/docker/volumes/.
Exit codes make orb scriptable: orb status (0/1/2), orb update -c (0 = current, 3 = outdated). → references/headless.md

Full command index

Every orbctl/orb subcommand. Read the linked reference for flags + examples.

Subcommand	What it does	Reference
`create`	Create a Linux machine (distro[:version] [name])	machines.md
`list` / `info`	List machines / show one machine's details (`-f json`)	machines.md
`default`	Get or set the default machine	machines.md
`start` / `stop` / `restart`	Start/stop/restart machine(s); bare `orb stop` stops all of OrbStack	machines.md
`delete`	Permanently delete machine(s) (`-a` all, `-f` force)	machines.md
`clone` / `rename`	Copy / rename a machine	machines.md
`export` / `import`	Save a machine to / restore from a `.tar.zst`	machines.md
`run` (alias `exec`/`shell`)	Run a command in a machine (`-m`, `-u`, `-w`, `ORBENV`)	machines.md
`push` / `pull`	Copy files Mac↔Linux	machines.md
`logs`	Unified machine logs (`-a` for all/debug)	machines.md, troubleshooting.md
`ssh`	Print SSH connection details	ssh.md
`usb` / `serial`	USB passthrough (attach/detach/list/info) / serial devices	machines.md
`docker`	Docker extension cmds: `volume` (clone/export/import), `migrate`	docker.md
`debug` (Pro)	Open a debug shell with tools in any container	docker.md
`k8s`	Show Kubernetes usage (`orb start k8s`)	kubernetes.md
`config`	get/set/add/remove/show/reset settings; `config docker` edits engine JSON	config.md
`status`	Is OrbStack running? (exit 0/1/2)	headless.md
`update`	Update OrbStack (`-c` check only, exit 3 if outdated)	headless.md
`top`	Live activity monitor (CPU/mem/disk/net)	troubleshooting.md
`doctor`	Verify Docker integration (`--fix` to repair)	troubleshooting.md
`report` / `reset`	Diagnostic bug report / factory reset (destroys data)	troubleshooting.md
`login` / `logout`	Manage OrbStack account + Pro license	config.md
`version`	Show version	-
`completion`	Generate shell completions (bash/zsh/fish/powershell)	config.md

Reference files

Read on demand:

references/machines.md - full machine lifecycle, run/exec, file transfer, per-VM CPU/memory/disk limits, isolation, cloud-init, USB/serial, and running macOS commands from Linux (mac, ORBENV).
references/docker.md - using docker under OrbStack: context, platform/ Rosetta, volume extension commands, migrating from Docker Desktop, debug shell, SSH-agent forwarding, checkpoints, credential store, engine config.
references/domains.md - .orb.local naming, custom domains label, HTTP-port override, wildcards, HTTPS, compose + k8s domains.
references/networking.md - port-forwarding, reaching the Mac host (host.docker.internal), direct container IPs, IP ranges, proxies, IPv6, LAN exposure, VPN, self-signed registry certs.
references/ssh.md - ssh orb patterns, port 32222, key path, IDE setup (VS Code / JetBrains / Fleet), Ansible, authorized_keys.
references/kubernetes.md - start/stop the cluster, kubectl context, kubeconfig, service domains, exposing services.
references/config.md - orb config subcommands and a full reference of every config key with its meaning.
references/headless.md - CLI/CI automation: install, service start/stop, status + exit codes, non-interactive provisioning, disabling admin prompts and context switching, JSON output.
references/troubleshooting.md - doctor/report/reset, restarting the engine, fixing the Docker context, Rosetta arch errors, cloud-init debugging, and the published-port "wedge" / route-loss gotchas.

orbstack-cli