Getting started

This guide takes you from a clean Mac to your first running container in about ten minutes.

Runbay is a native macOS GUI for Apple's container CLI. It does not bundle a runtime of its own — it drives Apple's containerization framework, which you install once as a signed package. Everything below assumes an Apple Silicon Mac; the framework does not support Intel.

1. Install Apple's container engine

Apple ships the runtime as a signed .pkg. Download the latest from the official releases page and run the installer:

Runbay targets CLI 1.0.0 or newer. CLI 1.1.0 is additive and safe. (1.0.0 removed the old v0 XPC API, so 0.x components can't interoperate — if you're on a 0.x build, upgrade.)

Confirm the install and start the engine:

container --version        # should print 1.0.0 or newer
container system start

macOS 26 Tahoe is recommended. Apple officially supports the CLI only on macOS 26, where you get custom networks and container-to-container networking. The app runs on macOS 15 too, but there you lose container-to-container networking and container network create — an Apple constraint the app reports honestly in-app.

2. Install Runbay

Runbay ships as a signed, notarized .dmg. Download it, open it, and drag Runbay into your Applications folder. There are three ways to get the same signed build:

  • runbay.app — the direct download (recommended).
  • GitHub Releases — the same builds with release notes and checksums: github.com/your-org/runbay/releases.
  • Polar — if you hold a commercial subscription, the build is attached to it as a download benefit.

Runbay's source is private, so there is no public build-from-source path. The app has one bundled dependency, SwiftTerm 1.13.0 (MIT) — its attribution ships in the NOTICES file next to the app.

3. Run the first-run doctor

Launch the app and open Help ▸ Setup Assistant (the first-run doctor). It runs seven live checks against your actual CLI and daemon:

  1. The container CLI is found on your PATH.
  2. Its version parses and meets the 1.0.0 baseline.
  3. The daemon is running and reachable.
  4. Container, image, network, and volume list surfaces all decode from the current JSON schema.

If anything is wrong, the doctor tells you exactly what and how to fix it — a missing engine, a stale CLI, or a stopped daemon. You can run the same checks headlessly without the UI:

Runbay --selftest        # 7 live CLI/JSON checks
Runbay --selftest-stack  # 13-step live stack deploy + teardown

4. Create your first container

Click New Container. The sheet gives you ports, volumes, environment variables, and advanced flags (--cap-add, --shm-size, stop signal, ulimits, and more), with a live, copyable container run … command preview that updates as you type. Nothing runs until you press Create.

For a real service, try PostgreSQL:

  • Image: postgres:15
  • Name: postgres
  • Env: POSTGRES_PASSWORD=devsecret

Prefer arm64 images where you can. Apple's linux/amd64 emulation can segfault JIT-heavy workloads (Node, .NET, MSSQL), so native arm64 images are more reliable.

5. Connect to it

Apple's runtime gives each container a direct IP (shown in the app's detail pane) — no port mapping required:

# Direct IP — copy it from the container detail view
psql -h 192.168.64.3 -U postgres -d postgres

Or publish a port to localhost if you prefer that workflow (CLI 0.3.0+):

container run -d -p 5432:5432 postgres:15

Where to go next

  • Stacks — deploy multi-container apps the CLI can't orchestrate on its own.
  • Agent setup — wire Runbay into Claude Code, Claude Desktop, or Cursor.
  • Sandboxes — run a coding agent in a disposable VM off your host.
  • Supervisor — keep long-running services alive (the CLI has no --restart).

Press ⌘K any time for the Command Palette (start postgres, logs nginx, exec redis, …).