# 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:

- [github.com/apple/container/releases](https://github.com/apple/container/releases)

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:

```bash
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:

<!-- TODO(first-release): the runbay.app download link goes live when the first signed DMG is published. -->
- **[runbay.app](https://runbay.app)** — the direct download (recommended).
- **GitHub Releases** — the same builds with release notes and checksums:
  [github.com/your-org/runbay/releases](https://github.com/your-org/runbay/releases).
  <!-- TODO(releases-repo): placeholder public releases-only repo (releases/issues/docs, no source); update when the real org/repo exists. -->
- **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:

```bash
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:

```bash
# 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+):

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

## Where to go next

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

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