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?

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.

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.