---
id: 12015
title: Day-0 prerequisites lack macOS container-runtime alternatives
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-gpt
createdAt: '2026-05-26T10:13:24Z'
updatedAt: '2026-05-26T17:34:41Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12015'
author: neo-opus-ada
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-26T17:34:41Z'
---
# Day-0 prerequisites lack macOS container-runtime alternatives

## Context

First-real-world cloud-deployment exercise on macOS (Apple Silicon) hit two prerequisite-table gaps immediately: the operator had no container runtime installed, and brew's `docker` + `docker-compose` formulae do not auto-wire the `docker compose` (no-dash) plugin path that every example in the Day-0 Tutorial and surrounding cloud-deployment guides assumes.

Both gaps are documentation, not substrate — the deployment works once they're resolved — but they block first-run on the most common 2026 macOS dev surface.

## The Problem

### Gap 1: Container-runtime alternatives are not surfaced

`Day0Tutorial.md` Prerequisites table (line 43) lists Docker Compose only:

| Tool | Check | Expected output |
|---|---|---|
| Docker Compose | `docker compose version` | a Compose version string |

`Day0Tutorial.md` Failure signatures table (line 49) lists exactly one fix:

> `docker: command not found` → Install Docker Desktop / Docker Engine or run the tutorial on a Docker-capable host.

No mention of Colima (the open-source Docker-compatible runtime that has become the de-facto macOS dev choice given Docker Desktop's commercial licensing posture), Podman, OrbStack, or any other Docker Engine-equivalent.

Grep across `learn/agentos/cloud-deployment/` + `ai/deploy/` confirms zero matches for `colima`, `podman`, or `orbstack` (V-B-A).

### Gap 2: macOS brew compose-plugin wiring is undocumented

Installing `docker` + `docker-compose` via brew on macOS does NOT auto-create the `~/.docker/cli-plugins/docker-compose` symlink that `docker compose` (no-dash) resolution depends on. The `docker-compose` (dash) binary works standalone, but every example in `Day0Tutorial.md`, `PipelineWiring.md`, `ai/deploy/Caddyfile`, and `ai/deploy/docker-compose.yml` uses the no-dash form.

A first-run user on macOS sees `docker: unknown command: docker compose` after `brew install docker docker-compose` and has no signpost from the guide that the symlink fix exists:

```bash
mkdir -p ~/.docker/cli-plugins
ln -sf /opt/homebrew/bin/docker-compose ~/.docker/cli-plugins/docker-compose
```

This is a known macOS+brew quirk but is not currently captured in the substrate.

## The Architectural Reality

Affected files (verified at dev HEAD via grep):

- `learn/agentos/cloud-deployment/Day0Tutorial.md` — Prerequisites + Failure signatures tables (lines 39-51).
- Cross-cutting reference: `learn/agentos/cloud-deployment/PipelineWiring.md` uses `docker compose` (no-dash) form throughout; same form in `ai/deploy/Caddyfile:9` and `ai/deploy/docker-compose.yml:5,131`. These need to stay consistent — the Day-0 fix is to make the prerequisite-to-form linkage discoverable, not to switch idioms.

Pure documentation surface — no code or compose changes required.

## The Fix

1. Expand the Day-0 Tutorial Prerequisites section with a runtime-choice subsection:
   - List Docker Desktop, Colima, Podman, OrbStack as supported runtimes; brief one-line description + install hint per row.
   - Explicit pointer to the canonical `docker compose` (no-dash) form that all examples use.

2. Add a Day-0 Tutorial Failure signatures row for the macOS brew quirk:

   | `docker: unknown command: docker compose` | brew did not wire the compose plugin path. | `mkdir -p ~/.docker/cli-plugins && ln -sf /opt/homebrew/bin/docker-compose ~/.docker/cli-plugins/docker-compose` |

3. Optional: a one-line sizing hint near the prerequisites pointing at Colima's `colima start --cpu N --memory N` (Memory Core primary store + Chroma + KB + MC + orchestrator + Ollama embedding model needs ~16 GiB VM minimum; ~24+ GiB once chat models like Gemma 4 31B are loaded).

The implementing PR may choose to inline this into Day-0 or factor out a sibling "Local Dev Setup" guide that Day-0 cross-references — either shape satisfies the AC.

## Contract Ledger

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `Day0Tutorial.md` Prerequisites + Failure-signatures tables | This ticket; ADR 0014 cloud-topology authority over the guide tree | Lists Docker Desktop / Colima / Podman / OrbStack as accepted runtimes; documents brew compose-plugin symlink quirk as a named failure signature | None — guide is the documentation surface; missing guidance = silent first-run failure | Inline guide subsections OR factored-out sibling guide cross-referenced from Day-0 | grep verification: zero `colima`/`podman`/`orbstack` matches under `learn/agentos/cloud-deployment/` + `ai/deploy/` (pre-fix); post-fix expected to return at least the prereq-table mentions |

## Decision Record impact

`none` — pure documentation enhancement under existing ADR 0014 cloud-topology authority.

## Acceptance Criteria

- [ ] A first-run macOS user without a pre-installed container runtime can discover Colima (or an equivalent open-source alternative) from `Day0Tutorial.md` Prerequisites without leaving the guide tree.
- [ ] `Day0Tutorial.md` Failure signatures table includes a row matching the brew compose-plugin symptom (`docker: unknown command: docker compose`) with the cli-plugins symlink fix.
- [ ] No claim that one specific runtime is "required" — the guide remains runtime-agnostic.
- [ ] `grep -ri 'colima' learn/agentos/cloud-deployment/Day0Tutorial.md` returns at least one hit (regression guard).
- [ ] If a sibling guide is factored out, `Day0Tutorial.md` cross-references it from the Prerequisites section.

## Out of Scope

- Per-runtime install scripts or automation. The guide lists options; operators choose.
- Linux-host runtime alternatives (rootless Podman, etc.) beyond a mention. The macOS surface is the immediate friction.
- CI/CD runtime guidance — that's `PipelineWiring.md` scope, not Day-0.
- Resource-sizing benchmarks beyond a single sizing hint.

## Avoided Traps

- Recommending Colima as a hard default in the substrate — rejected; this is a docs gap, not a policy mandate. Linux servers, ARM clouds, etc. should keep their existing runtime.
- Inlining the symlink fix at every `docker compose` usage site — rejected; single-source-of-truth in the Prerequisites section + failure-signature row.
- Filing as a `bug` — rejected; the guide is functional for users who already have Docker installed, and the gap is additive documentation rather than incorrect content.

## Related

- #12014 — sibling first-real-world deployment friction (orchestrator co-location follow-up). Both surfaced by the same external-deployment exercise.
- ADR 0014 — cloud-deployment topology (substrate authority for the guide tree).
- `learn/agentos/cloud-deployment/Day0Tutorial.md` — primary fix surface.

## Handoff Retrieval Hints

- Grep: `grep -rni 'colima\|podman\|orbstack' learn/agentos/ ai/deploy/` — pre-fix returns zero matches; post-fix returns at least the prereq table.
- Semantic: "Day-0 prerequisites macOS container runtime", "Colima docker compose plugin brew symlink".
- File anchor: `learn/agentos/cloud-deployment/Day0Tutorial.md:39-51` (the Prerequisites + Failure signatures tables).

## Timeline

- 2026-05-26T10:13:26Z @neo-opus-ada added the `documentation` label
- 2026-05-26T10:13:26Z @neo-opus-ada added the `enhancement` label
- 2026-05-26T10:13:27Z @neo-opus-ada added the `ai` label
- 2026-05-26T10:20:08Z @neo-opus-ada cross-referenced by #12016
- 2026-05-26T10:27:52Z @neo-opus-ada cross-referenced by #12017
- 2026-05-26T10:46:25Z @neo-opus-ada cross-referenced by #12019
- 2026-05-26T11:54:16Z @neo-gpt assigned to @neo-gpt
- 2026-05-26T12:00:19Z @neo-gpt cross-referenced by PR #12020
- 2026-05-26T13:06:57Z @neo-gpt referenced in commit `8f2bef4` - "chore(ci): retrigger checks (#12015)"
- 2026-05-26T13:09:13Z @neo-opus-ada cross-referenced by #12022
- 2026-05-26T13:34:37Z @neo-opus-ada cross-referenced by #12025
- 2026-05-26T15:40:34Z @neo-opus-ada cross-referenced by #12026
- 2026-05-26T15:46:16Z @neo-opus-ada cross-referenced by PR #12024
- 2026-05-26T16:11:23Z @neo-opus-ada cross-referenced by #12028
- 2026-05-26T16:12:27Z @neo-opus-ada cross-referenced by #12029
- 2026-05-26T16:16:32Z @neo-gpt referenced in commit `967f051` - "docs(day0): document macOS container runtimes (#12015)"
- 2026-05-26T16:16:32Z @neo-gpt referenced in commit `9b90897` - "chore(ci): retrigger checks (#12015)"
- 2026-05-26T16:47:05Z @neo-gpt referenced in commit `09a1db5` - "docs(day0): document macOS container runtimes (#12015)"
- 2026-05-26T16:47:05Z @neo-gpt referenced in commit `c55a384` - "chore(ci): retrigger checks (#12015)"
- 2026-05-26T17:34:41Z @tobiu referenced in commit `0467cc5` - "docs(day0): document macOS container runtimes (#12015) (#12020)

* docs(day0): document macOS container runtimes (#12015)

* chore(ci): retrigger checks (#12015)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-26T17:34:41Z @tobiu closed this issue

