# Migrating from Docker or OrbStack

Runbay is a GUI for Apple's `container` runtime, not for Docker. Moving over is mostly
about re-pulling images and re-declaring your services — Apple's runtime is a different engine, so
some things transfer cleanly and some things genuinely don't. The migration assistant is honest about
which is which.

## The migration assistant

Open **Help ▸ Migrate from Docker…**. When your Docker/OrbStack daemon is reachable, the assistant:

1. **Detects** what you're running — Docker Desktop, OrbStack, or a bare `docker` CLI.
2. **Enumerates** your images, containers, volumes, and compose projects.
3. **Guides a selective re-pull** — pick the images you want and it pulls them into Apple's runtime
   via `container image pull`.
4. **Bridges compose projects** into the built-in Stack importer, with sandbox-scoped file access, so
   a `docker-compose.yml` becomes a reviewable [Stack](stacks.md).

## What migrates, and what does not

| Thing                | Migrates?     | How / why                                                                 |
|----------------------|---------------|---------------------------------------------------------------------------|
| **Images**           | ✅ Re-pulled  | Layers are re-fetched from the registry into Apple's runtime.             |
| **Compose projects** | ✅ As Stacks  | Bridged into the importer; unmappable keys surface as warnings.           |
| **Containers**       | ⚠️ Re-created | Enumerated for reference; you re-run them (often via a Stack).            |
| **Volume *data***    | ⛔ Not yet    | Volumes are listed, but the actual data is **not** copied. See below.     |

### The volume-data caveat (be explicit with yourself)

The assistant **enumerates** your Docker/OrbStack volumes so you can see what exists — but it does
**not** copy the data inside them. Image *layers* re-pull; volume *data* does not transfer. If a
volume holds a database or uploads you care about, back it up and restore it yourself before you tear
down the old setup. Automated volume-data copy (a tar-pipe migration) is planned but not shipped.

## Things that are different by design

Apple's runtime isn't Docker with a new coat of paint, so a few habits change:

- **Direct IPs instead of port mapping.** Each container gets a dedicated IP (e.g.
  `192.168.64.3`), shown in the app — you can connect straight to it, no `-p` needed. Port publishing
  (`-p/--publish`) still exists if you prefer localhost.
- **No Docker socket / API.** Apple's runtime exposes no Docker socket, so tools that expect
  `/var/run/docker.sock` — including Testcontainers — won't find one. A bridge (socktainer) is under
  evaluation, but today there is no socket.
- **Each container is its own lightweight VM**, not a shared-kernel namespace. That's the security
  win; it's also why the mental model differs.
- **Prefer arm64 images.** `linux/amd64` emulation can segfault JIT-heavy workloads (Node, .NET,
  MSSQL). Re-pull the arm64 variant where one exists.

## A sensible order of operations

1. Run the [first-run doctor](getting-started.md) so you know the engine and CLI are healthy.
2. Open the migration assistant; re-pull the images you actually use.
3. Re-create services as [Stacks](stacks.md) — import your compose file and review the warnings.
4. **Manually move any volume data you need** (it does not migrate automatically).
5. Only then decommission Docker Desktop / OrbStack.

Coming from compose specifically? The [Stacks guide](stacks.md) covers the importer and how warnings
work in detail.