How to Use OrbStack: The Beginner's Guide (First Install, the Migrate Rule, First Compose, and the .orb.local Lesson)

CodexFuse Team · 2026-11-01T03:22:12.052Z · 12 min read

OrbStack is the fast, lightweight Docker Desktop alternative for macOS. This beginner's guide walks through install, the migrate rule, Docker context switching, your first compose stack, .orb.local domains, Linux machines, Kubernetes, and resource limits.

Mac developers who run containers eventually hit the same wall: Docker Desktop sits heavy at idle, takes forever to boot, and the subscription question hangs over every new hire. Learning how to use OrbStack is the escape hatch most of them end up taking — it is a lightweight, fast Docker Desktop alternative built for macOS that runs your existing Docker workflows without a single change. OrbStack is a drop-in Docker Desktop replacement for the Mac: it starts in seconds, sips about 0.1% CPU when idle, and hands every container an automatic .orb.local domain so you stop juggling localhost ports. This is the orbstack tutorial for beginners: the first install, the migrate rule, the Docker-context lesson, your first Compose stack, Linux machines, and the resource-limits rule — the whole beginner arc on one page. New to containers entirely? Start with our Docker beginner guide — OrbStack is a runtime, and the Docker concepts underneath still matter.

What Is OrbStack?

OrbStack is a commercial Docker Desktop alternative for macOS (macOS 14+, Apple Silicon and Intel) that runs Docker containers, Compose stacks, a built-in Kubernetes cluster, and full Linux machines inside one lightweight virtual machine. It implements the full Docker API and passes the Docker test suite, so every docker and docker compose command you already know works unchanged — only the engine underneath changes.

The design is what makes it fast. Instead of Docker Desktop's heavier VM, OrbStack runs a single lightweight Linux VM with a shared kernel — the same idea as WSL2 on Windows — with its services purpose-built in Swift, Go, Rust, and C. File sharing is built on VirtioFS with custom dynamic caching, so bind mounts stay quick, and everything — container images, volumes, machine files — is browsable from your Mac through a mount at ~/OrbStack. The vendor's efficiency docs put idle CPU at about 0.1%, often dropping to 0%, and a fresh install uses less than 10 MB of disk with fully dynamic growth afterward.

One thing to know before you fall in love: OrbStack is macOS-only. Linux readers should stay on plain Docker, and Windows readers are not covered at all — the vendor site lists macOS 14+ with Apple Silicon and Intel, full stop.

OrbStack for Beginners: the 10-Step First-Run Arc

Here is the exact arc this orbstack tutorial follows — the orbstack for beginners path from zero to a compose stack on a real domain in about half an hour.

1. Confirm you are on a Mac. OrbStack needs macOS 14+ on Apple Silicon or Intel. On Linux or Windows, stop here — this tool is not for your machine.
2. Install it. Run brew install --cask orbstack, then open the OrbStack app once so it finishes setup and installs the docker and orb CLI tools.
3. Let the trial run. New installs get a 30-day Pro trial and then settle into the free tier for personal, non-commercial use. You will know the price before you ever pay anything.
4. Apply the migrate rule. If you are coming from Docker Desktop, run orb docker migrate BEFORE uninstalling Docker Desktop. Originals stay untouched, and you verify everything works before the old runtime goes away.
5. Switch the Docker context. Run docker context use orbstack, then docker ps to confirm the OrbStack engine answers.
6. Run your first container. docker run --rm hello-world — and notice how fast the engine is awake. Peek at the OrbStack menu-bar app: containers, images, volumes, and networks tabs are all there.
7. Bring up your first Compose stack. A normal docker compose up -d in any project folder just works — same files, same commands, same output.
8. Learn the .orb.local lesson. Open service.project.orb.local instead of localhost:port — automatic domains with zero-config HTTPS, no port juggling.
9. Spin up a Linux machine. orb create ubuntu dev gives you a full Ubuntu box in under a minute for the things containers cannot do.
10. Set your resource limits. OrbStack's memory cap defaults to 8 GB and releases unused memory back to macOS — adjust it in Settings before you start wondering where the RAM went.

How Do You Install OrbStack?

The install is one line. If you already have Homebrew, run brew install --cask orbstack — the vendor's canonical command from its own homepage. (Older tutorials write plain brew install orbstack, which resolves to the same cask.) If Homebrew is not on your Mac yet, our Homebrew beginner guide gets you from zero to your first cask install.

brew install --cask orbstack
open -a OrbStack        # finish setup; installs the docker and orb CLI tools
orb version             # confirm the install — v2.2.5 was current at write time
docker --version        # the Docker CLI is ready

After install, open the app once. That first launch finishes setup, installs the CLI tools, and asks about migration — say yes if you are moving off Docker Desktop, or come back to it later from File > Migrate Docker Data. At the time of writing, the current release is v2.2.5 (released October 23, 2026) — verify with orb version, since this is a fast-moving product and the number will climb.

What Is the Migrate Rule?

The migrate rule is the one rule that prevents migration disasters: move your data before you uninstall Docker Desktop. Uninstalling first strands your images, volumes, and containers in a VM you can no longer boot. Everything people search for as "orbstack migrate docker desktop" comes down to this: migrate first, verify, and only then remove the old runtime.

The current command, straight from the vendor's install docs, is orb docker migrate — or the same operation from the menu (File > Migrate Docker Data). The orb command list also documents a bare orb migrate for moving Docker Desktop data, so if a tutorial shows one form and your terminal prefers the other, both are documented paths to the same destination. (Beware older blog posts that wrote orb migrate docker — that syntax is outdated.)

After migration, run docker images and docker ps -a through the OrbStack engine and eyeball the results: your images, stopped containers, and named volumes should all be there. Only when everything checks out should Docker Desktop leave the machine.

How Does the Docker Context Switch Work?

Docker contexts are the switchboard that lets two runtimes live on one Mac. OrbStack creates a Docker context named orbstack; switching engines is a one-liner, and nothing is ever uninstalled by switching:

docker context use orbstack        # point Docker at OrbStack
docker context use desktop-linux   # point it back at Docker Desktop
docker context use colima          # if you also run Colima

The orbstack docker context lesson matters most to migrators: your images and containers live with the engine, not the CLI, so switching contexts switches which engine — and which data — your commands see. OrbStack can also update the /var/run/docker.sock symlink to point at its own engine (it asks for admin access), which keeps tools that talk to the socket directly working without configuration changes. If you ever uninstall OrbStack, switch the context back to desktop-linux first so the CLI is not left pointing at a missing engine.

Your First Compose Stack on OrbStack

The first compose on OrbStack is deliberately boring: a standard Compose file, a standard command, standard output. That boredom is the point — nothing about your projects changes.

# compose.yaml
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"

docker compose up -d
docker compose ps          # running — via the OrbStack engine
open http://web.compose-project.orb.local   # skip the port; see the next section

Ports still work exactly as before, so localhost:8080 remains valid. But the compose run is also where the .orb.local lesson starts paying off, which is why the snippet above opens the automatic domain instead of the port.

How Do the .orb.local Domains Work?

The orbstack orb.local system is zero-config: every container gets an automatic domain, and Compose services get predictable ones: a container named web is reachable at web.orb.local, and a Compose service named api in project nextbigthing answers at api.nextbigthing.orb.local. HTTPS works out of the box with dynamic certificates, so web services never need port numbers in URLs.

The niceties stack up fast: orb.local itself renders an index page of all running containers; Linux machines get machine-name.orb.local; Kubernetes services answer at *.k8s.orb.local. Custom domains come from the dev.orbstack.domains label on a container, and custom wildcards like *.example.local are supported (the .local TLD only). This is the feature people quietly fall in love with — it kills the localhost:3000 versus localhost:8080 juggling that plagues every multi-service project.

What Are OrbStack Linux Machines?

OrbStack Linux machines are full Linux virtual machines — not containers — for the jobs containers cannot do: running systemd services, testing kernel-level tooling, or keeping a persistent dev box. They spin up in under a minute on a fast connection:

orb create ubuntu dev          # a new Ubuntu machine named "dev"
orb -m dev ./setup.sh          # run one command on it
orb ssh                        # show SSH connection details
orb create --arch amd64 ubuntu x86box   # an x86 machine on Apple Silicon (Rosetta)

On Apple Silicon, OrbStack uses Rosetta to run Intel (x86_64/amd64) images and machines with good performance — much faster than emulation — and --platform linux/amd64 on a docker run works the same way. SSH is built in: OrbStack multiplexes access to all machines through one SSH server, and your SSH agent is forwarded automatically. If your machine needs to be reachable from the internet rather than your laptop, that is the moment to leave the laptop entirely — see our guide on what is VPS hosting for the rented-server lane.

How Do You Set OrbStack Resource Limits?

OrbStack's resource model is dynamic by default: it only uses what your programs actually use, and memory it is not using is handed back to macOS. The one guardrail that matters is the memory cap, which defaults to 8 GB. You change it in the OrbStack Settings panel or with orb config. CPU is not a reservation — the engine takes what it needs and nothing more, which is exactly why idle shows up at roughly 0.1% CPU.

Practical rule: if containers start getting OOM-killed on a memory-hungry stack, raise the cap before you blame the app. And note what the vendor does not promise — you will find old blog posts claiming a "50% of system resources" default, but the official settings docs document only the 8 GB memory cap, so treat the 50% figure as folklore, not fact.

OrbStack vs Docker Desktop vs Colima: Which Should a Beginner Pick?

The docker desktop alternative mac question has three serious answers and one honorable mention. Here is the beginner-level cheat sheet:

The orbstack vs colima decision is the classic GUI-versus-terminal split: Colima is free, open source, and CLI-only (brew install colima, then colima start), while OrbStack adds the menu-bar app, automatic domains, and Linux machines on top of the same drop-in compatibility. Podman Desktop sits off to the side as the security-first pick — a cross-platform, open-source GUI for daemonless, rootless containers, covered in our Podman beginner guide. And the extensions caveat is real: OrbStack explicitly does not support Docker Desktop extensions, so if your workflow leans on a specific extension, check for a built-in equivalent before migrating.

OrbStack also ships a built-in single-node Kubernetes cluster for development — orb start k8s brings it up with kubectl bundled — which makes it a credible local Kubernetes playground for the same price as the Docker runtime: free, for personal use.

Sources

• OrbStack homepage — install command (brew install --cask orbstack), macOS 14+ / Apple Silicon + Intel, "starts in seconds" — orbstack.net (fetched 2026-11-01)
• OrbStack install docs — orb docker migrate, Docker contexts (orbstack / desktop-linux), /var/run/docker.sock symlink — docs.orbstack.dev/install (fetched 2026-11-01)
• OrbStack domains docs — .orb.local naming, zero-config HTTPS, dev.orbstack.domains label, orb.local index, *.k8s.orb.local — docs.orbstack.dev/docker/domains (fetched 2026-11-01)
• OrbStack machines docs + commands — orb create, orb -m, orb ssh, orb version, Rosetta x86 — docs.orbstack.dev/machines (fetched 2026-11-01)
• OrbStack pricing + licensing docs — free for personal non-commercial use; Pro $8/user/month or $96/year; 30-day trial — orbstack.dev/pricing (fetched 2026-11-01)
• OrbStack settings + efficiency docs — 8 GB default memory cap, dynamic allocation, ~0.1% CPU idle, VirtioFS file sharing, ~/OrbStack mount — docs.orbstack.dev/settings (fetched 2026-11-01)
• OrbStack release notes — v2.2.5 released October 23, 2026 — docs.orbstack.dev/release-notes (fetched 2026-11-01)
• OrbStack Kubernetes docs — built-in single-node cluster, orb start k8s, bundled kubectl — docs.orbstack.dev/kubernetes (fetched 2026-11-01)
• Tech Insider Docker-alternatives roundup (Oct 2026) — no Docker Desktop extensions equivalent in OrbStack — tech-insider.org (fetched 2026-11-01)
• Setapp Docker Desktop alternatives review — Colima and Podman Desktop positioning — setapp.com (fetched 2026-11-01)
• Pickuma OrbStack deep review — full Docker API compatibility, <10 MB fresh install, dynamic disk growth — pickuma.com (fetched 2026-11-01)
• The New Stack OrbStack deep dive — shared-kernel VM architecture, Swift/Go/Rust/C services — thenewstack.io (fetched 2026-11-01)

Frequently Asked Questions

Is OrbStack free?

Yes — free for personal, non-commercial use. OrbStack Pro costs $8 per user per month (or $96 billed annually) and is required for any business or commercial use, including freelancers; new installs include a 30-day Pro trial. Per-user licensing covers up to five devices.

Is OrbStack better than Docker Desktop?

For Mac developers, usually yes on speed and efficiency: OrbStack starts in seconds, idles near 0% CPU, and adds automatic .orb.local domains and full Linux machines. Docker Desktop still wins on cross-platform parity and its extensions marketplace — OrbStack has no extensions equivalent. If your workflow depends on a specific extension, stay put or check for a built-in OrbStack alternative first.

Does OrbStack work on Linux or Windows?

No — OrbStack is macOS-only (macOS 14+, Apple Silicon and Intel). On Linux, plain Docker is the native lane; on Windows, WSL2 plus Docker Desktop remains the standard setup.

Can I run OrbStack and Docker Desktop at the same time?

Yes. They are separate Docker contexts — docker context use orbstack and docker context use desktop-linux switch which engine your commands talk to. Keep Docker Desktop installed until you have migrated and verified everything with orb docker migrate.

Does OrbStack replace Docker itself?

No — it replaces Docker Desktop's runtime layer, not Docker. Your images, Compose files, Dockerfiles, and CLI commands all stay exactly the same; only the engine running them changes. That is why the migration is painless: there is nothing new to learn, just something old to stop waiting on.