OrbStack Docs

Appearance

Frequently asked questions ​

Please search for your question, or open an issue if you can't find an answer.

Is OrbStack free? ​

OrbStack is a paid product now that it's no longer in beta. You must purchase a license for freelance, business, and commercial use.

  • Personal use: free
  • Business and commercial use: $8/user/mo
    • This includes non-profit organizations.
  • Educational use: Free licenses may be requested, subject to approval.
  • Use for open-source development: Free licenses may be requested for non-commercial projects, subject to approval. Commercial open-source developers must purchase a license.

We hope that the performance, speed, reliability, simplicity, and potential cost savings of OrbStack will justify the price. Contact us if you have questions or custom needs.

You have a 30-day grace period to purchase a license.

Why a subscription?

Look, we get it: subscriptions suck. We don't like them either. But we think that subscriptions are the best way to align our incentives with yours, and we want to be transparent about it. If we're not living up to your expectations, then you can cancel.

We also plan to introduce online services to simplify developer workflows, which would not be sustainable to run without subscriptions.

Lifetime licenses are unsustainable. OrbStack's components need continuous updates: compatibility with new macOS versions, Linux kernel, and other assorted pieces, as well as new features to stay competitive.

Major version upgrades incentive us to withhold features for months when they would otherwise be released much faster; we'd rather deliver gradual improvements so you get continuous value. Also, major upgrades have a high risk of introducing breaking changes, bugs, and other issues due to a lack of gradual testing.

1-year updates + fallback perpetual: More or less a yearly subscription in disguise? Just cancel if you don’t want to keep paying. JetBrains does a hybrid of this + subscription — not entirely opposed to it, but it shares a lot of these issues (e.g. incentivizes slower feature development). Realistically, would anyone revert to a year-old version and stay on it forever?

It's a hard problem.

Is OrbStack open-source? ​

No, OrbStack is a closed-source product, but some components are open-source. See above for licensing and pricing plans.

How is OrbStack different from Docker Desktop? ​

OrbStack is a drop-in replacement for Docker Desktop that's fast, light, simple, and easy to use. See OrbStack vs. Docker Desktop for a detailed comparison.

Switching from Docker Desktop is painless: just open OrbStack and get started.

How is OrbStack different from Colima? ​

OrbStack is a drop-in replacement for Colima that's that's fast, light, simple, and easy to use. It's also more reliable and seamless, especially when it comes to networking, and has better compatibility with Docker Desktop. See OrbStack vs. Colima for a detailed comparison.

Switching from Colima is painless: just open OrbStack and get started.

Can I use the same Docker tools? ​

OrbStack provides an unmodified Docker engine with a setup similar to Docker Desktop, resulting in excellent compatibility. This means that the tools you know and love will work out of the box, including:

See Third-party tools for more details.

How does licensing work? SSO, organizations, batch purchases? ​

You can purchase a batch of multiple licenses, use Google and SAML SSO, and create organizations with automatic license assignment and auto-invite.

See Licensing for more details.

Why are you asking for admin? ​

OrbStack asks for admin to perform optional setup tasks:

  • To install command-line tools if you don't already have them
  • To improve compatibility with third-party tools by creating a symlink at /var/run/docker.sock

You're free to deny admin access if you're not comfortable with it.

In the future, we may add performance improvements and features that require admin. We try to avoid it whenever possible, but sometimes there's no other way.

Command-line tools

If you choose to allow admin, the following tools will be installed to /usr/local/bin:

  • orb, orbctl: Manage OrbStack and use Linux machines
  • docker, docker-compose, docker-buildx: Docker command-line tools
  • docker-credential-osxkeychain: Provider for saving registry logins in the macOS keychain

Is admin required? ​

No, admin is optional. You can use all OrbStack features without it.

Is Kubernetes supported? ​

Yes. OrbStack can run a lightweight cluster for local development, complete with GUI and network integration. See Kubernetes for more details.

Why is there an 8 TB data file? ​

The 8 TB data.img file in OrbStack's data is a virtual disk image. Don't worry about the size; it's a special type of file known as a sparse file, meaning that it only takes as much space as you use, and automatically shrinks when you delete data. It does not take up 8 TB of disk space.

Sparse files are an APFS feature that provides a fast, efficient, and flexible way to store large files with varying usage. Time Machine supports them, so your backups will not be affected. The large 8 TB size allows OrbStack to manage the disk dynamically so you don't have to worry about having too much or too little disk space.

WARNING

Even though Time Machine supports sparse files, Migration Assistant does not. If you're moving to a new Mac using Migration Assistant, please delete the data.img file (or use tar to back it up). We're hoping Apple fixes this soon.

To find the true size of the file, run du -h ~/.orbstack/data/data.img, or look at "size on disk" in Finder's info panel. Sparse files have two sizes: an apparent size (8 TB in this case), and size on disk (actual usage). Many tools show the apparent size, but the size on disk is what matters for disk space.

If you have third-party apps complaining about the file, please see the GitHub issue. Since macOS uses sparse files extensively, we'd like to move the ecosystem forward and fix compatibility issues with them.

Is this an Electron app? ​

No, OrbStack is a native macOS app written in Swift. Underlying components are written in a mix of Go, Rust, and C.

How can I exclude data from backups? ​

To exclude containers, images, volumes, and Linux machines from backups, add ~/.orbstack/data to your exclusion list.

Why are Intel and Apple Silicon separate? ​

There's no technical reason that OrbStack couldn't be a universal app. However, most of OrbStack's size comes from architecture-specific Linux images and binaries, meaning that app and update sizes would be doubled as a universal app. We don't think it's worth the tradeoff, but we may revisit this decision in the future.

What can't you do? ​

Great question! We think OrbStack is pretty awesome and we're always improving it, but there are some things that we can't do yet. Here are some of the most common ones, many of which are planned:

In most cases, no trade-offs were made to achieve our efficiency goals.

How does it work? Why is it fast? ​

OrbStack uses a lightweight Linux virtual machine with tightly-integrated, purpose-built services and networking written in a mix of Swift, Go, Rust, and C. See Architecture for more details.

How do I go back to Docker Desktop? ​

Stop OrbStack in the app and change the Docker context back to desktop-linux:

bash
docker context use desktop-linux
docker context use desktop-linux

See Reverting for more details.

How do I go back to Colima? ​

Stop OrbStack in the app, then restart Colima. See Reverting for more details.

Colima will restore the Docker context automatically.

Can I use Podman? ​

Built-in support for running containers with Podman is being considered. Vote on the feature request to help us prioritize it.

In the meantime, you can create a Linux machine and use Podman in it. Bind mounts, port forwarding, etc. will work as expected. For example:

bash
orb create ubuntu
orb sudo apt install podman
orb sudo podman run -it --rm -p 80:80 docker.io/docker/getting-started
orb create ubuntu
orb sudo apt install podman
orb sudo podman run -it --rm -p 80:80 docker.io/docker/getting-started

Why is macOS 13.0+ required? ​

Supporting macOS Catalina 10.15 is not feasible because none of the virtualization APIs used by OrbStack existed back then.

In theory, supporting macOS Big Sur 11 is possible, but there are still missing APIs that would lead to a poor experience. It's also rarely requested.

macOS Monterey 12.0–12.2 has the necessary APIs, but there were critical virtualization bugs that would lead to a poor experience (performance issues and crashes). That's why we only support macOS 13.0 and newer.

Cannot connect to the Docker daemon at unix://.orbstack/run/docker.sock ​

This error means that the Docker client is trying to use OrbStack when it's not running. Start OrbStack to fix it.

If you just uninstalled OrbStack ​

Change the Docker context back to default to fix the error.

bash
docker context use default
docker context use default

See Reverting for more details.

© 2024 Orbital Labs, LLC