Skip to content
Back to search

IcontainU

A native SwiftUI macOS GUI for Apple's container — smart container creation, one-click Compose, and a built-in MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jeffqiu1989--icontainu/badge.svg)](/listings/jeffqiu1989--icontainu)

HTML

<a href="/listings/jeffqiu1989--icontainu"><img src="/api/listings/jeffqiu1989--icontainu/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 284 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # IcontainU
  3. **A native macOS GUI for Apple's [`container`](https://github.com/apple/container).**
  4. *`I`* — Apple's lowercase‑i lineage (iOS, iPhone) · *`contain`* — container · *`U`* — UI
  5. Built with SwiftUI. No Electron, no daemon of its own — it just drives the `container` you already have.
  6. English | [中文](README_zh.md)
  7. </div>
  8. ---
  9. ## Highlights
  10. Two things make IcontainU worth your dock:
  11. | ⚡ Smart Create | 🧩 One‑click Compose |
  12. | --- | --- |
  13. | <img src="docs/screenshots/Auto_fill.gif" alt="Auto-fill demo" /> | <img src="docs/screenshots/Compose_Demo.gif" alt="Compose demo" /> |
  14. | **Drop in an image, the form fills itself.** Ports, mounts, and the env vars the entrypoint *actually needs* (like `MYSQL_ROOT_PASSWORD`) are read from the image and pre‑filled. No more copying `docker run` snippets. | **Bring a whole stack up in one click.** Import a `compose.yaml` and Up the project in dependency order, with `healthcheck` gating. Projects persist across `down` and restarts — and it works around Apple `container`'s broken container‑to‑container DNS so service names just resolve. |
  15. ## More features
  16. - **⚓ Local Kubernetes** — a sidebar section spins up a single-node Kubernetes cluster in-process; `kubectl` works out of the box (kubeconfig merged into `~/.kube/config` and set as the current context), and it needs **no proxy** — the KIND node ships with every image `kubeadm` needs, so bootstrap pulls nothing. See [Local Kubernetes](#local-kubernetes).
  17. - **🐧 Machines that just work** — presets pointing at official *init‑ready* images (Alpine, Rocky UBI‑init), so machines actually boot. CPU, memory, and home‑mount are all settable.
  18. - **📦 Smart image pull** — pulls only your host architecture, and is registry‑mirror aware with a one‑click **DaoCloud preset** (9 registries, individually toggleable) that leaves no trace on local images.
  19. - **🔨 Image building** - build container images from a Dockerfile via the shared BuildKit builder, with no-cache toggle, live build log, and per-config build history.
  20. - **🃏 Everything on a card** — Start / Stop / Shell / Logs / Delete per container, plus a live **stats** tab and streaming logs.
  21. - **✨ Friction removers** — tap to copy an IP or `ip:port`, tap a mount to open it in Finder, local‑image autocomplete, and Docker‑style auto‑naming.
  22. - **🚀 Frictionless setup** — first launch auto‑installs the kernel and monitors `container` health for you.
  23. - **🤖 MCP server** - a built-in [Model Context Protocol](https://modelcontextprotocol.io) server exposes every container, image, machine, volume, network, and Compose operation as a tool, so Claude Code, OpenCode, or any MCP client can drive IcontainU remotely over HTTP with a Bearer API key. See [docs/mcp_server.md](docs/mcp_server.md) for the full 25-tool API.
  24. ## Screenshots
  25. | Containers | Create a container |
  26. | --- | --- |
  27. | ![Containers](docs/screenshots/Containers.png) | ![Create a container](docs/screenshots/Create_Container.png) |
  28. | Create a machine | Images |
  29. | --- | --- |
  30. | ![Create a machine](docs/screenshots/Create_Machine.png) | ![Images](docs/screenshots/Images.png) |
  31. | Registry mirrors | Built-in MCP server |
  32. | --- | --- |
  33. | ![Registry mirrors](docs/screenshots/Mirrors.png) | ![Built-in MCP server](docs/screenshots/Mcp_server.png) |
  34. ## Requirements
  35. - **Apple silicon** Mac (M‑series), **macOS 26** or newer
  36. - Apple [`container`](https://github.com/apple/container/releases) ≥ 1.0.0 installed
  37. Start the system once from the CLI so it installs the kernels (faster than the in‑app download):
  38. ```bash
  39. container system start
  40. container system status # should report: running
  41. ```
  42. Without a running `container` system the app still opens, but the sidebar stays empty.
  43. ## Download & install
  44. Download `IcontainU-v0.6.0.zip` from [Releases](../../releases), unzip, and move `IcontainU.app` to Applications.
  45. Not notarized — on first launch, right‑click → Open, or run:
  46. ```bash
  47. xattr -d com.apple.quarantine /Applications/IcontainU.app
  48. ```
  49. ## Build from source
  50. Requires the Swift 6.2 toolchain (Xcode 26).
  51. ```bash
  52. swift build && swift run IcontainU
  53. # package a signed .app:
  54. ./scripts/package-app.sh
  55. ```
  56. ## Status & known limitations
  57. **0.6.0** — early, but useful day to day.
  58. - `Shell` opens an external terminal (Terminal.app, Warp, Ghostty, or iTerm2 — see [Terminal](#terminal)) — no embedded terminal yet.
  59. - System configuration is **view‑only** in the app; edit it via the CLI.
  60. - Menu bar support is under development.
  61. - Compose does not support `build:` - use the standalone **Build** feature to build images, then reference them by tag in `image:`.
  62. ## Terminal
  63. `Shell` (on a container) and the machine **Run** button open an external terminal
  64. and drop you into `container exec` / `container machine run`. Pick which terminal
  65. under **System → Shell terminal**:
  66. - **Terminal.app** (default)
  67. - **Warp** — needs a one-time setup for full features; see below
  68. - **Ghostty**
  69. - **iTerm2**
  70. Terminals that aren't installed are shown as *(not installed)* and can't be
  71. selected; the app falls back to Terminal.app if a previously chosen terminal is
  72. removed.
  73. ### Configuring Warp
  74. Warp gives its container shells the full Warp experience (blocks, completions,
  75. the input editor) only when it "Warpifies" the subshell. Two one-time steps:
  76. 1. **Tell Warp to recognize `container exec`.** In Warp, go to
  77. **Settings → Warpify → Subshells** and add these to the **Added commands** list:
  78. - `container exec` — for container shells
  79. - `container machine run` — for machine shells (optional)
  80. 2. **Make sure the container has `bash`.** Warpify needs `bash`, `zsh`, or
  81. `fish` — plain `sh` won't work. IcontainU execs `bash` when the container has
  82. it and falls back to `sh` otherwise (so Alpine and other sh‑only images still
  83. open, just without Warpify).
  84. The first time you open a container shell in Warp, IcontainU shows a one‑time
  85. reminder of step 1.
  86. ## Local Kubernetes
  87. A dedicated **Kubernetes** sidebar section spins up a local, single-node
  88. Kubernetes cluster — no `container k8s` plugin or external CLI required;
  89. IcontainU drives the cluster in-process over the same `container` XPC the
  90. rest of the app uses.
  91. - **Create / list / delete / export kubeconfig** from the UI, with a real
  92. progress bar for the ~1 GB node-image pull.
  93. - **`kubectl` works out of the box** — the cluster's kubeconfig is merged into
  94. `~/.kube/config` and set as the current context, targeting
  95. `127.0.0.1:<host-port>`.
  96. ## Compose reference
  97. IcontainU supports a **practical subset** of the Compose spec. Anything unsupported is surfaced as a warning banner at import — **never silently dropped**.
  98. <b>Supported fields &amp; what's not</b>
  99. | Field | Notes |
  100. | --- | --- |
  101. | `image` | — |
  102. | `command` | string **or** array form |
  103. | `ports` | numeric and `host:container/proto` |
  104. | `environment` | list `["K=V"]` **and** map `{K: V}` |
  105. | `volumes` | named (`vol:/data`) and bind (`/host:/data[:ro]`, incl. relative `./`) |
  106. | `networks` | per‑service and top‑level |
  107. | `depends_on` | start order **and** `condition: service_healthy` |
  108. | `healthcheck` | `test`, `interval`, `timeout`, `retries`, `start_period` |
  109. | `container_name`, `user` | — |
  110. | top‑level `networks:` / `volumes:` | — |
  111. Plus `${VAR}` / `.env` interpolation at parse time.
  112. **Not supported:**
  113. | Field | Notes |
  114. | --- | --- |
  115. | `build:` | — |
  116. | `restart:` | — |
  117. | `deploy.replicas` / scale | — |
  118. | `env_file` | — |
  119. | `profiles` | — |
  120. | `secrets` | — |
  121. | `configs` | — |
  122. | `extends` | — |
  123. | YAML anchors | — |
  124. | advanced `driver_opts` | — |
  125. <b>Project isolation &amp; multi‑network</b>
  126. - **Every project is namespaced.** Containers, volumes and networks are prefixed with the project name, so two projects that each declare a `db` service run side by side. Pinning the **same** `container_name:` in two projects fails loudly instead of hijacking.
  127. - **Multi‑network is fully supported.** A service on several networks resolves each peer on a network the two containers actually share.
  128. <b>Healthcheck gating</b> — how <code>service_healthy</code> is honored
  129. Apple `container` 1.0.0 has no native healthcheck, so IcontainU runs the probe via `container exec` **during Up** to gate `depends_on: { condition: service_healthy }`. There is no always‑on healthy/unhealthy badge.
  130. - If a gated dependency never becomes healthy, Up fails but the dependency is left running so its logs explain why — fix the compose file and re‑Up.
  131. - A `service_healthy` dependency with **no** healthcheck warns and is treated as start‑order only.
  132. <b>Runtime constraints</b> — Apple <code>container</code> on macOS 26 (not IcontainU bugs)
  133. - **Container‑to‑container DNS is broken on macOS 26 — IcontainU works around it** by injecting `<service> → real IP` into each container's `/etc/hosts` after Up.
  134. - **Database data dirs on bind mounts — the chown problem and how to fix it.**
  135. On macOS, the bind-mount root is owned by the host user and refuses `chown`. Images that `chown` their data directory at startup fail with "Operation not permitted" when the data directory *is* the mount-point root:
  136. ```
  137. # MySQL / MariaDB
  138. chown: changing ownership of '/var/lib/mysql/': Operation not permitted
  139. # PostgreSQL ≤17
  140. chmod: changing permissions of '/var/lib/postgresql/data': Operation not permitted
  141. chown: changing ownership of '/var/lib/postgresql/data': Operation not permitted
  142. ```
  143. **Affected versions:**
  144. - **PostgreSQL 17 and below** — `PGDATA` defaults to `/var/lib/postgresql/data`, which is the mount-point root → fails.
  145. - **PostgreSQL 18+** — `PGDATA` defaults to a subdirectory (`/var/lib/postgresql/18/docker`) → no issue, works out of the box.
  146. - **MySQL / MariaDB** — all versions are affected.
  147. **Fix:** point the data directory at a *subdirectory* of the mount instead. The image-specific setting that controls this differs per image:
  148. | Image | Fix | Example compose snippet |
  149. | --- | --- | --- |
  150. | PostgreSQL ≤17 | Set `PGDATA` to a subdirectory | `environment: PGDATA: /var/lib/postgresql/data/pgdata` |
  151. | MySQL / MariaDB | Pass `--datadir` pointing to a subdirectory | `command: ["--datadir", "/var/lib/mysql/data"]` |
  152. Ready-to-use templates with the fix pre-applied are in [`samples/`](samples/):
  153. - [`template-postgres-17.yaml`](samples/template-postgres-17.yaml) — PostgreSQL 17 with bind-mounted data dir
  154. - [`template-mysql.yaml`](samples/template-mysql.yaml) — MySQL 8 with bind-mounted data dir
  155. Import via **Compose → New Project**, edit the password and host path, then Up.
  156. - **Non‑root images need `user: "0"` on a named volume**, otherwise they can't write their data dir.
  157. ## Samples
  158. The [`samples/`](samples/) directory ships Compose templates you can import via **Compose → New Project** and Up directly. Each one is verified to run on IcontainU.
  159. | Stack | Services | Notes |
  160. |---|---|---|
  161. | [postgresql-pgadmin](samples/postgresql-pgadmin/) | PostgreSQL + pgAdmin | `${VAR}` placeholder template — edit passwords before import |
  162. | [gitea-postgres](samples/gitea-postgres/) | Gitea + PostgreSQL | Named volumes, `restart: always` |
  163. | [nextcloud-postgres](samples/nextcloud-postgres/) | Nextcloud + PostgreSQL | |
  164. | [nextcloud-redis-mariadb](samples/nextcloud-redis-mariadb/) | Nextcloud + Redis + MariaDB | **Multi-network** demo (separate dbnet / redisnet) |
  165. | [wordpress-mysql](samples/wordpress-mysql/) | WordPress + MariaDB | |
  166. | [elasticsearch-logstash-kibana](samples/elasticsearch-logstash-kibana/) | ELK stack (ES 8 + Logstash + Kibana) | Full `healthcheck` + `depends_on: condition: service_healthy` |
  167. | [prometheus-grafana](samples/prometheus-grafana/) | Prometheus + Grafana | `user: "0"` for named-volume write; bind mounts for config |
  168. | [postgres-healthcheck](samples/postgres-healthcheck/) | PostgreSQL + Alpine | Minimal healthcheck / `service_healthy` demo |
  169. | [kafka-cluster-kraft](samples/kafka-cluster-kraft/) | Kafka 4.3.1 KRaft (3 controllers + 3 brokers) | Advertised listeners on hostnames; depends_on startup |
  170. | [redis-cluster](samples/redis-cluster/) | Redis 7 cluster | 3-master / 3-replica with auto-failover; `cluster-announce-hostname` + `/etc/hosts` DNS workaround |
  171. | [redis-cluster-envoy-proxy](samples/redis-cluster-envoy-proxy/) | Redis cluster + Envoy proxy | Slot-aware Envoy proxy at `host:6379` — plain `redis-cli`, no `-c` flag needed |
  172. | [`template-mysql.yaml`](samples/template-mysql.yaml) | MySQL 8 (single) | Standalone template; bind-mount data dir with `--datadir` subdirectory (macOS chown fix) |
  173. | [`template-postgres-17.yaml`](samples/template-postgres-17.yaml) | PostgreSQL 17 (single) | Standalone template; `PGDATA` subdirectory bind-mount (macOS chown fix) |
  174. > **macOS bind-mount note:** some samples use bind-mounted data directories. On macOS the mount root is owned by the host user and can't be `chown`'d. Images that need `chown` on their data dir (MySQL, PostgreSQL ≤ 17) are pointed at a **subdirectory** via `--datadir` / `PGDATA` — the templates already handle this. See the [Compose reference](#compose-reference) for details.
  175. ## MCP server
  176. IcontainU ships an embedded [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI client can operate containers, images, machines, volumes, networks, and Compose projects on your behalf - useful for "bring this stack up and verify it's healthy" workflows driven from Claude Code, OpenCode, or any MCP-compatible client.
  177. - **Transport**: MCP over Streamable HTTP at `/mcp` (swift-nio server, default port `3000`).
  178. - **Auth**: Bearer API key, generated and managed in the in-app **MCP** panel. Constant-time comparison; no key, no access.
  179. - **Bind**: `127.0.0.1` (localhost only) by default; switch to `0.0.0.0` in the panel to reach it from the LAN.
  180. **25 tools** across 6 resource groups:
  181. | Resource | Tools |
  182. | --- | --- |
  183. | Container | `list`, `create`, `start`, `stop`, `delete`, `exec`, `logs`, `inspect` |
  184. | Image | `list`, `pull`, `delete` |
  185. | Machine | `list`, `boot`, `stop`, `delete` |
  186. | Volume | `list`, `create`, `delete` |
  187. | Network | `list`, `create`, `delete` |
  188. | Compose | `list`, `up`, `down`, `status` |
  189. Full tool schemas, parameters, and examples: [docs/mcp_server.md](docs/mcp_server.md).
  190. Quick start from a client config (`.mcp.json`):
  191. ```json
  192. {
  193. "mcpServers": {
  194. "containers": {
  195. "url": "http://127.0.0.1:3000/mcp",
  196. "headers": { "Authorization": "Bearer <your-api-key>" }
  197. }
  198. }
  199. }
  200. ```
  201. ## License & acknowledgements
  202. Licensed under the Apache License 2.0 — see [LICENSE](LICENSE). Built on Apple's `container` and `containerization`; see [NOTICE](NOTICE) for attribution.
  203. Developed with the assistance of vibe coding (AI-assisted development).
  204. Thanks to the [LINUX DO](https://linux.do) community for providing a platform for communication and learning.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.