IcontainU

KO | EN

gitlite — search

#python #hacktoberfest #llm #go #linux #docker #java #windows #awesome #cli #kubernetes #awesome-list #mcp #ios

(★ 75)

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

IcontainU Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# IcontainU

**A native macOS GUI for Apple's [`container`](https://github.com/apple/container).**

*`I`* — Apple's lowercase‑i lineage (iOS, iPhone) · *`contain`* — container · *`U`* — UI

Built with SwiftUI. No Electron, no daemon of its own — it just drives the `container` you already have.

English | [中文](README_zh.md)

</div>

---

## Highlights

Two things make IcontainU worth your dock:

| ⚡ Smart Create | 🧩 One‑click Compose |
| --- | --- |
| <img src="docs/screenshots/Auto_fill.gif" alt="Auto-fill demo" /> | <img src="docs/screenshots/Compose_Demo.gif" alt="Compose demo" /> |
| **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. |

## More features

- **🐧 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.
- **📦 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.
- **🔨 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.
- **🃏 Everything on a card** — Start / Stop / Shell / Logs / Delete per container, plus a live **stats** tab and streaming logs.
- **✨ 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.
- **🚀 Frictionless setup** — first launch auto‑installs the kernel and monitors `container` health for you.
- **🤖 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.

## Screenshots

| Containers | Create a container |
| --- | --- |
| ![Containers](https://raw.githubusercontent.com/jeffqiu1989/IcontainU/main/docs/screenshots/Containers.png) | ![Create a container](https://raw.githubusercontent.com/jeffqiu1989/IcontainU/main/docs/screenshots/Create_Container.png) |

| Create a machine | Images |
| --- | --- |
| ![Create a machine](https://raw.githubusercontent.com/jeffqiu1989/IcontainU/main/docs/screenshots/Create_Machine.png) | ![Images](https://raw.githubusercontent.com/jeffqiu1989/IcontainU/main/docs/screenshots/Images.png) |

| Registry mirrors | Built-in MCP server |
| --- | --- |
| ![Registry mirrors](https://raw.githubusercontent.com/jeffqiu1989/IcontainU/main/docs/screenshots/Mirrors.png) | ![Built-in MCP server](https://raw.githubusercontent.com/jeffqiu1989/IcontainU/main/docs/screenshots/Mcp_server.png) |

## Requirements

- **Apple silicon** Mac (M‑series), **macOS 26** or newer
- Apple [`container`](https://github.com/apple/container/releases) ≥ 1.0.0 installed

Start the system once from the CLI so it installs the kernels (faster than the in‑app download):

```bash
container system start
container system status   # should report: running
```

Without a running `container` system the app still opens, but the sidebar stays empty.

## Download & install

Download `IcontainU-v0.5.0.zip` from [Releases](../../releases), unzip, and move `IcontainU.app` to Applications.

Not notarized — on first launch, right‑click → Open, or run:

```bash
xattr -d com.apple.quarantine /Applications/IcontainU.app
```

## Build from source

Requires the Swift 6.2 toolchain (Xcode 26).

```bash
swift build && swift run IcontainU
# package a signed .app:
./scripts/package-app.sh
```

## Status & known limitations

**0.5.0** — early, but useful day to day.

- `Shell` opens Terminal.app — no embedded terminal yet.
- System configuration is **view‑only** in the app; edit it via the CLI.
- Menu bar support is under development.
- Compose does not support `build:` - use the standalone **Build** feature to build images, then reference them by tag in `image:`.

## Compose reference

IcontainU supports a **practical subset** of the Compose spec. Anything unsupported is surfaced as a warning banner at import — **never silently dropped**.

<b>Supported fields &amp; what's not</b>

| Field | Notes |
| --- | --- |
| `image` | — |
| `command` | string **or** array form |
| `ports` | numeric and `host:container/proto` |
| `environment` | list `["K=V"]` **and** map `{K: V}` |
| `volumes` | named (`vol:/data`) and bind (`/host:/data[:ro]`, incl. relative `./`) |
| `networks` | per‑service and top‑level |
| `depends_on` | start order **and** `condition: service_healthy` |
| `healthcheck` | `test`, `interval`, `timeout`, `retries`, `start_period` |
| `container_name`, `user` | — |
| top‑level `networks:` / `volumes:` | — |

Plus `${VAR}` / `.env` interpolation at parse time.

**Not supported:**

| Field | Notes |
| --- | --- |
| `build:` | — |
| `restart:` | — |
| `deploy.replicas` / scale | — |
| `env_file` | — |
| `profiles` | — |
| `secrets` | — |
| `configs` | — |
| `extends` | — |
| YAML anchors | — |
| advanced `driver_opts` | — |

<b>Project isolation &amp; multi‑network</b>

- **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.
- **Multi‑network is fully supported.** A service on several networks resolves each peer on a network the two containers actually share.

<b>Healthcheck gating</b> — how <code>service_healthy</code> is honored

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.

- 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.
- A `service_healthy` dependency with **no** healthcheck warns and is treated as start‑order only.

<b>Runtime constraints</b> — Apple <code>container</code> on macOS 26 (not IcontainU bugs)

- **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.
- **Database data dirs on bind mounts — the chown problem and how to fix it.**

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:

```
  # MySQL / MariaDB
  chown: changing ownership of '/var/lib/mysql/': Operation not permitted

# PostgreSQL ≤17
  chmod: changing permissions of '/var/lib/postgresql/data': Operation not permitted
  chown: changing ownership of '/var/lib/postgresql/data': Operation not permitted
  ```

**Affected versions:**
  - **PostgreSQL 17 and below** — `PGDATA` defaults to `/var/lib/postgresql/data`, which is the mount-point root → fails.
  - **PostgreSQL 18+** — `PGDATA` defaults to a subdirectory (`/var/lib/postgresql/18/docker`) → no issue, works out of the box.
  - **MySQL / MariaDB** — all versions are affected.

**Fix:** point the data directory at a *subdirectory* of the mount instead. The image-specific setting that controls this differs per image:

| Image | Fix | Example compose snippet |
  | --- | --- | --- |
  | PostgreSQL ≤17 | Set `PGDATA` to a subdirectory | `environment: PGDATA: /var/lib/postgresql/data/pgdata` |
  | MySQL / MariaDB | Pass `--datadir` pointing to a subdirectory | `command: ["--datadir", "/var/lib/mysql/data"]` |

Ready-to-use templates with the fix pre-applied are in [`samples/`](samples/):
  - [`template-postgres-17.yaml`](samples/template-postgres-17.yaml) — PostgreSQL 17 with bind-mounted data dir
  - [`template-mysql.yaml`](samples/template-mysql.yaml) — MySQL 8 with bind-mounted data dir

Import via **Compose → New Project**, edit the password and host path, then Up.
- **Non‑root images need `user: "0"` on a named volume**, otherwise they can't write their data dir.

## Samples

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.

| Stack | Services | Notes |
|---|---|---|
| [postgresql-pgadmin](samples/postgresql-pgadmin/) | PostgreSQL + pgAdmin | `${VAR}` placeholder template — edit passwords before import |
| [gitea-postgres](samples/gitea-postgres/) | Gitea + PostgreSQL | Named volumes, `restart: always` |
| [nextcloud-postgres](samples/nextcloud-postgres/) | Nextcloud + PostgreSQL | |
| [nextcloud-redis-mariadb](samples/nextcloud-redis-mariadb/) | Nextcloud + Redis + MariaDB | **Multi-network** demo (separate dbnet / redisnet) |
| [wordpress-mysql](samples/wordpress-mysql/) | WordPress + MariaDB | |
| [elasticsearch-logstash-kibana](samples/elasticsearch-logstash-kibana/) | ELK stack (ES 8 + Logstash + Kibana) | Full `healthcheck` + `depends_on: condition: service_healthy` |
| [prometheus-grafana](samples/prometheus-grafana/) | Prometheus + Grafana | `user: "0"` for named-volume write; bind mounts for config |
| [postgres-healthcheck](samples/postgres-healthcheck/) | PostgreSQL + Alpine | Minimal healthcheck / `service_healthy` demo |
| [kafka-cluster-kraft](samples/kafka-cluster-kraft/) | Kafka 4.3.1 KRaft (3 controllers + 3 brokers) | Advertised listeners on hostnames; depends_on startup |
| [redis-cluster](samples/redis-cluster/) | Redis 7 cluster | 3-master / 3-replica with auto-failover; `cluster-announce-hostname` + `/etc/hosts` DNS workaround |
| [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 |
| [`template-mysql.yaml`](samples/template-mysql.yaml) | MySQL 8 (single) | Standalone template; bind-mount data dir with `--datadir` subdirectory (macOS chown fix) |
| [`template-postgres-17.yaml`](samples/template-postgres-17.yaml) | PostgreSQL 17 (single) | Standalone template; `PGDATA` subdirectory bind-mount (macOS chown fix) |

> **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.

## MCP server

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.

- **Transport**: MCP over Streamable HTTP at `/mcp` (swift-nio server, default port `3000`).
- **Auth**: Bearer API key, generated and managed in the in-app **MCP** panel. Constant-time comparison; no key, no access.
- **Bind**: `127.0.0.1` (localhost only) by default; switch to `0.0.0.0` in the panel to reach it from the LAN.

**25 tools** across 6 resource groups:

| Resource | Tools |
| --- | --- |
| Container | `list`, `create`, `start`, `stop`, `delete`, `exec`, `logs`, `inspect` |
| Image | `list`, `pull`, `delete` |
| Machine | `list`, `boot`, `stop`, `delete` |
| Volume | `list`, `create`, `delete` |
| Network | `list`, `create`, `delete` |
| Compose | `list`, `up`, `down`, `status` |

Full tool schemas, parameters, and examples: [docs/mcp_server.md](docs/mcp_server.md).

Quick start from a client config (`.mcp.json`):

```json
{
  "mcpServers": {
    "containers": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}
```
## License & acknowledgements

Licensed under the Apache License 2.0 — see [LICENSE](LICENSE). Built on Apple's `container` and `containerization`; see [NOTICE](NOTICE) for attribution.

Developed with the assistance of vibe coding (AI-assisted development).

Thanks to the [LINUX DO](https://linux.do) community for providing a platform for communication and learning.

IcontainU

IcontainU Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

IcontainU

IcontainU Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README