DEV Community: yukihiro amadatsu

I ran 156 real-world docker compose projects on Apple's container. The failures fell into patterns a machine can fix

yukihiro amadatsu — Tue, 28 Jul 2026 14:03:35 +0000

This is the English version of my Japanese post on Zenn.

Back in July I measured Apple's container runtime against 29 samples from Docker's official awesome-compose collection and concluded: not your main dev stack yet.

Something kept bugging me about that verdict, though. Official samples are polite. Real-world compose files are not: secrets live outside the file, services join a pre-existing reverse-proxy network, data sits in bind mounts under /mnt/docker-volumes because that's how the self-hosting community rolls. If you want the real compatibility picture, you have to feed the runtime the messy stuff.

So this time I fed it everything: all 161 entries of Haxxnet/Compose-Examples, the self-hosting community's staple collection. This post is the report — the counts, a taxonomy of why things fail, and what happened when I taught a tool to fix the mechanical failures automatically: full-stack startup went from 39% to 50%.

Setup

Corpus: 161 entries, of which 159 have a compose file
Parse/validate: all 159
Startup test: the 156 without a build: section (image-only), each started, classified, and torn down by a script
Two arms per project, back to back, on the same binary: A = plain up, B = up --from-docker-compose (auto-fix on — more on that below)
Secrets and passwords left as placeholders. This is the deliberately hostile "run up without reading the README" condition
120-second hard timeout per up (this timeout misclassifies exactly one project later — I'll get to it)
Environment: macOS 26 / Apple silicon, container 1.1.0, with opossum v0.15.0 as the orchestration layer — a thin translator from compose to container CLI calls, so this sweep doubles as its compatibility test

Reproducing it is essentially this (drop --from-docker-compose for the no-fix arm):

container system start                    # once
sudo container system dns create opossum  # once (name resolution)
opossum up --from-docker-compose          # in each compose directory
opossum ps                                # classification comes from this output
opossum down -v                           # cleanup

Each run lands in one of six classes:

Class	Meaning
FULL-UP	every service running
PARTIAL	some services running
CRASH	a container crashed right after start
STARTED-NONERUN	`up` finished within 120s but nothing was running (instant exits, image pull failures — mixed, not individually audited)
PREFLIGHT	stopped before starting (host port taken, missing external network, …)
TIMEOUT	cut off by the 120s timeout

The raw numbers first

Parsing: all 159 files load. Zero parse errors, zero unreadable files. Real-world compose files always contain fields Apple's runtime has no counterpart for — container_name (149 of them), restart (143) — so "ignore unsupported fields and list them in a warning" turns out to be exactly the policy that makes the whole corpus loadable.

The mass startup, no modifications (arm A):

Class	Count
FULL-UP	61
PARTIAL	21
CRASH	9
STARTED-NONERUN	40
PREFLIGHT	23
TIMEOUT	2

61 of 156 (39%) reach full startup with zero modifications: gitea, jellyfin, grafana, home-assistant, minio, syncthing, nginx-proxy-manager, code-server — the self-hosting staples just come up.

Read 39% as a conservative floor. Secrets are unfilled, so any stack that requires a DB password can't get past PARTIAL by construction. The 40 STARTED-NONERUN projects failed for mixed reasons (instant exits, pull failures) that I didn't audit one by one, so I can't even claim all 40 are "broken". Set things up the way the README says and the number only goes up.

For scale: the official 29-sample survey had 14 working as-is (48%). This corpus is measured under much harsher rules — no secrets, all services must be running — and still lands at 39%. My pre-sweep prediction that real-world files would do far worse than polished samples was wrong.

Counting the failures

Classifying the 95 failures gives two groups.

Group 1: nothing to do with Apple's container

Configuration that isn't there yet, essentially:

Unset secrets crash the DB (the main source of PARTIAL — this is my test condition, not a bug)
Host port already taken (5000/7000 is usually macOS's AirPlay Receiver; explicit mappings like "5000:5000" fail identically under docker compose. The one real difference is bare ports like - "3000": docker compose escapes to a random host port, Apple's runtime requires an explicit one, so it mirrors the number and can collide)
Bind mounts of placeholder paths like /path/to/my/data (you're meant to fill those in)
external networks that don't exist (you're meant to create the proxy network first)

For reference, the first sweep of this corpus counted the top diagnostics: 20 DB crashes from unset secrets, 12 host-port collisions, 12 placeholder-path bind failures, 10 missing external networks. All of these would need the same adjustments on Docker Desktop or on any other machine (with a caveat — see the limits section).

Group 2: failures that are Apple-container-specific

Two kinds here. One is /var/run/docker.sock mounts — tools that operate Docker itself, Portainer-style, 18 in the first sweep. Apple's runtime has no Docker-compatible socket, so no compose edit can save these.

The other kind is the runtime model difference: places where Apple's container is architecturally unlike Docker, so compose patterns that work on Docker fall over. These are fixable by changing what the compose says, and they collapse into just two patterns:

Pattern 1: a data directory on a named volume, where Postgres's initdb refuses to initialize because the directory "isn't empty" (19 of 156 affected)
Pattern 2: a bind-mounted data directory that MySQL/Postgres can't chown, so the entrypoint dies immediately (31 of 156 affected; 18 overlap with pattern 1)

32 projects in total, a third of all failures. Both are perfectly ordinary compose idioms on Docker — that's the point. The behavior below is as of container 1.1.0.

Pattern 1: named volumes are mount points

A Docker named volume is just a directory. An Apple container named volume is a whole filesystem, mounted. ext4 creates a lost+found recovery directory (where fsck puts rescued files) at the root of every filesystem it makes — the one you see under / or /home on any Linux box. So the volume is non-empty from the moment it's mounted.

Docker:            volume = empty directory
Apple container:   volume = ext4 mount point (lost+found included)

Postgres's initdb refuses a non-empty data directory. Which means -v pgdata:/var/lib/postgresql/data — a line written in thousands of compose files — doesn't work as-is. The fix is one env var: point PGDATA one level below the mount point.

Pattern 2: bind mounts can't be chowned

Apple's runtime gives every container its own lightweight VM, and bind mounts reach into that VM via virtiofs — a protocol that exposes a host directory to a VM as a shared filesystem. The files are only visible through the share; their owner stays the host. So chown from inside the container fails. MySQL and Postgres images chown their data directory at the top of the entrypoint. Result: instant death by Operation not permitted.

Self-hosting compose files love bind-mounting data to host paths like /mnt/docker-volumes/<app>/, which is why this pattern hits so often. The fix: put the data directory (just that) on a named volume — those chown fine.

If the fix is deterministic, a machine can apply it

Both patterns have a mechanical diagnosis and a single known fix. So instead of making humans read the caveats section, I taught opossum to do it. In migration mode (up --from-docker-compose) it detects the known patterns and writes only the fixes into a separate file, compose.opossum.yaml, layered on top of your compose at startup. Two design rules:

The original docker-compose.yml is never touched. docker compose doesn't know this filename and ignores it, so the same directory keeps working with both tools
Every generated fix carries a comment explaining what changed, why, how to verify it, and how to undo it. The intended reader is not just you but also whatever AI agent is working on your project — the file explains itself without context

So how many did it save?

Same 156 projects, same binary, arm A (no fix) vs arm B (auto-fix):

Class	A: no fix	B: auto-fix	Δ
FULL-UP	61	78	+17
PARTIAL	21	7	−14
CRASH	9	5	−4
STARTED-NONERUN	40	40	0
PREFLIGHT	23	23	0
TIMEOUT	2	3	+1

The full per-project ledger (one row per project: A class, B class, which fixes were written) and the sweep harness are published as a gist. Every number from here on can be recounted from that file.

A summary table can hide regressions that happen to be offset by improvements, so check the ledger row by row: nothing got worse. All 61 projects that were FULL-UP in A stayed FULL-UP in B (zero collateral damage from the auto-fix). What moved: 16 PARTIAL and 1 CRASH graduated to FULL-UP, 2 CRASH became PARTIAL, 1 CRASH became TIMEOUT — 20 changes, all in the improving direction. Everything else kept its class. bitwarden (passwords), paperless-ngx (document scanning), seafile (file sync), matomo (analytics), sonarqube (code quality) — apps that all carry a Postgres or MySQL behind them, which is exactly why they were tripping over the two data-directory patterns.

Where the 32 generated fix files went: 17 graduated to FULL-UP (8 from pattern 2 alone, 8 from both patterns, 1 from pattern 1 alone). The other 15 got a correct fix but stayed down behind a different wall — port collisions, docker.sock — one project can fail for several reasons at once, and now there's a number on that.

The timeout misclassified one project

TIMEOUT went 2 → 3. I looked at the new one: the auto-fix got it past its CRASH, which meant initialization finally ran to completion — in 154 seconds, past the 120-second cutoff, with every service up. Classified TIMEOUT, actually a success.

Count it and you get 79 (51%). But arm A has two TIMEOUTs of its own that I did not audit the same way, and reclassifying only the borderline cases that flatter the result isn't fair. So this article's number stays what the table says: 78.

78 of 156 — 39% to 50%. Half of a real-world compose corpus reaches full startup without you editing a single line.

One measurement lesson for the road: a hard timeout is necessary if you don't want a sweep to hang forever, and it will still misclassify the borderline. Read every guarded measurement as a floor. Both 39% and 50% here are floors in that sense.

What I didn't do / can't claim

One machine, one pass per arm. The 23 PREFLIGHTs include this Mac's own port situation; some would pass elsewhere
Unfilled secrets is not how anyone actually runs these stacks. Filling them would convert much of PARTIAL to FULL-UP; I didn't measure that
The sweep runs below any restart policy (143 of the 159 files declare one). Docker compose would absorb some first-boot crashes — a DB winning a startup race on retry — via restart: always, so part of PARTIAL/CRASH may be my measuring layer's behavior rather than runtime incompatibility. Not yet isolated
No docker compose control run. "These would need the same adjustments on Docker" is inferred from the failure logs, not measured
The pattern-2 fix moves where your data lives (bind mount → named volume). Harmless for fresh stacks; migrating existing data is out of scope
docker.sock, kernel modules (WireGuard), cgroup-reading JVMs (old Elasticsearch): not fixable by editing compose, still broken

What counting taught me

With 29 official samples I thought about compatibility as a table: this field supported, that field not. What 156 real-world files taught me is that the real picture is a distribution — what fraction just works, and where the failures cluster. Measured that way: 40% works untouched, most failures are configuration rather than the runtime, the runtime-specific failures collapse into a couple of mechanically fixable patterns, and the unfixable remainder is the part that depends on Docker-the-infrastructure — which stays broken until Apple ships a compatible socket or volume seeding.

Apple's container compatibility story has moved from "not yet" to "fails predictably". Predictable failures are automatable fixes. And the 156-project ledger points at exactly which gap should close next.

If you run your own compose files through this, I'd love to hear how they land — especially the ones that break in ways not on this list.

Apple's container makes no sense as a Docker replacement — until you see it as a box for AI agents

yukihiro amadatsu — Tue, 21 Jul 2026 13:36:52 +0000

日本語版 (Japanese version): Apple containerの不可解な設計、実は"AIエージェント用の箱"を作ってるだけ説

A design that keeps losing benchmarks

When I measured Apple's container runtime, the honest numbers were rough: every container gets its own VM at roughly 270–400 MB, throwaway containers start 4–10× slower than Docker's, and a named volume can only attach to one running container at a time. Judged as a docker compose replacement, it looks like Apple deliberately picked a losing design.

And that's the puzzle. Apple obviously knows how Docker Desktop's shared-VM model wins on density — that design has had a decade of tuning. They looked at it and walked away anyway. Why?

Here's the hypothesis this post explores: Apple isn't building a box for your dev stack. It's building a box for code you don't trust. And in 2026, the most important untrusted code around is the AI coding agent. Read the design through that lens and every "flaw" starts looking like a decision.

This is an interpretation piece, but every claim below is anchored to something measured on my machine or shipped in public. At the end I'll list predictions that would falsify the whole reading.

Exhibit 1: the parts list is suspicious

Line up what Apple has shipped over the past year — as parts, not features.

Per-VM isolation. Each container gets its own lightweight VM with its own kernel. Worst possible choice for "many containers, cheaply"; best possible choice for "one untrusted thing, strongly isolated."

For contrast: Microsoft went the opposite way the very same month. WSL containers (public preview, June 2026) run in one shared utility VM with namespace isolation — the same "many, cheaply" side Docker sits on. Two OS vendors shipped first-party containers at the same time and made opposite isolation choices. That tells you what each was optimizing for.

But here's the interesting part: Docker itself picked per-VM when the workload is an agent. Docker Sandboxes (January 2026) isolates Claude Code, Codex, and friends in a dedicated microVM per agent. The company whose whole model is "share one kernel, run many" chose a VM boundary the moment the tenant became untrusted code. Two players, different starting points, same answer. I take that as evidence about what these boxes are for.

mcpbridge. Apple officially announced agentic coding in Xcode 26.3, exposing Xcode's capabilities over MCP. The implementation is a bundled binary, xcrun mcpbridge, that translates MCP into XPC — Apple's entitlement-gated IPC. A portability protocol, deliberately re-rooted into Apple's permission model: MCP tools treated as capabilities, the same shape as iOS app permissions. In the Xcode 27 beta there's a second layer: ACP (Agent Client Protocol) — an open protocol from Zed, not Apple — governs which agents may connect at all. MCP says what an agent can do; ACP says who gets in. Two gates, both built from other companies' open standards folded into Apple's own permission model.

Models on the host, tools in the box. Apple container has no GPU/ANE passthrough. Inference was never meant to live in the container: Foundation Models run host-side on the Neural Engine, and the containers hold the tools.

Container machines. WWDC26 also brought persistent Linux VMs — the long-lived counterpart to container run's disposable ones.

Boundaries and gates everywhere. That's a lot of parts for a "Docker alternative."

Exhibit 2: this is how Apple has always done safety

There's a lineage here. Private Cloud Compute's design principle was "don't trust the operator — prove it structurally." The iOS sandbox is the same shape: apps run free inside the sandbox, and hit a checkpoint only when crossing a boundary — contacts, camera, location. The checkpoint is an entitlement check or that permission dialog you've tapped a thousand times. Call it the gate.

free inside the boundary → one gate at the crossing

Now compare that to how today's coding agents are kept safe: an approval prompt for every action, a human in the loop for each step. Apple's pattern is the inverse — total freedom inside, one gate at the edge. Per-VM containers are the boundary; mcpbridge + ACP are the gate. The parts line up with the philosophy.

For agents this difference is fundamental. Per-action approval burns human attention continuously. A boundary model justifies --dangerously-skip-permissions structurally: whatever happens, it happens inside the box. Since an agent's whole value is autonomous, continuous operation, I'd bet agent platforms converge on the boundary model. That bet is the core of this post.

Exhibit 3: you can already build the box — with a compose file

Here's the observation I most want to share. To run the boundary model on a Mac today you need some way to declare what the agent gets. iOS has entitlements for this. The container world, it turns out, already has a vocabulary for it — the compose file:

volumes: (bind mount) = the files the agent may see
environment: + .env = the secrets it holds
ports: / host gateway = its reach back to the host
networks: / network_mode: = how far it reaches out

I didn't want to leave that as theory, so I built it. (Apple container doesn't read compose files itself; I used opossum, a compose-compatible orchestrator I work on, as the translator — but the star here is the compose vocabulary, not the tool.)

name: agent-sandbox

services:
  agent:
    build: .            # node:22 + git + Claude Code
    user: node          # non-root: Claude Code refuses full-auto mode as root
    working_dir: /work
    volumes:
      - ./work:/work    # the ONLY host files the agent sees; results land here
    mem_limit: 4g       # the default ~1 GiB guest is tight for node + build + test
    cpus: 4
    environment:
      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}   # value lives in .env

Read differently, this file is a capability manifest: this agent sees ./work and nothing else, holds this one token, gets 4 GB. No new machinery — ten-year-old compose vocabulary, reread.

Does it actually work? On my machine (macOS 26, container 1.1.0): I gave the in-VM Claude Code one line — "fix the failing test in /work/demo and commit" — in full-auto mode. It found the bug (an addition function doing a - b), fixed it, ran the tests, and committed, with zero human input. The results appeared on the host via the bind mount. Whatever the agent had done in there, the only thing that could reach my Mac was the contents of ./work.

And the benchmark numbers that looked so bad in my first post? For this workload they stop mattering. Agent tasks run for minutes, so a ~1 s VM boot is noise; 270–400 MB per VM is nothing when you're granting the agent 4 GB anyway. The puzzle from the intro resolves.

The weak side: egress

Files, secrets, and host reach are all declarable. Outbound network is the rough edge. What I measured (macOS 26 / container 1.1.0):

Goal	Possible today?	How
Block everything	✅	`network_mode: none` (loopback only)
Block internet, keep host	✅	an internal network (`--internal`)
Destination allowlist	✅ (enforced)	internal network + an allowlist proxy on the host
Native per-container domain allowlist	❌ not yet (Apple; Docker Sandboxes has it — see below)	(prediction #1)

Row three is the one worth knowing. On an internal network the internet route physically disappears, so the only way out is a proxy you run on the host. An agent that ignores http_proxy and connects directly simply gets nothing. The allowlist is enforced, not advisory. (In-guest iptables allowlists, for the record, didn't work in my tests — allowed destinations dropped too. The proxy approach is the right one.)

"Why not just use Docker Sandboxes?"

Fair question — I asked it myself, so I put it through its paces (Docker Desktop 4.78, docker sandbox v0.12):

docker sandbox create shell .        # a box with the current dir as workspace
docker sandbox exec <box> uname -a   # → Linux ... 6.12.67-linuxkit aarch64

What I found:

It's a real microVM: a linuxkit-kernel Linux, one per agent — same idea as Apple's per-VM
The workspace mounts at the same path as the host
It has the native domain allowlist Apple lacks:

docker sandbox network proxy <box> --policy deny --allow-host example.com

With that set, example.com returns 200 from inside the box and anything else gets 403. Better: bypassing the proxy env vars entirely (curl --noproxy '*') fails even for the allowed host — there is no direct route out, the MITM proxy is the only exit. Enforced, same property as the internal-network setup above. The box even ships a docker CLI inside, so containers-in-VM works out of the box.

Honestly, as an agent box today, Docker Sandboxes is the most complete option: native allowlists, multiple agents, save for snapshots, reset in seconds.

What interests me is not which is better but that the two approaches express the box's permissions differently. Docker Sandboxes is imperative: you run commands to configure the box. The compose approach is declarative: mounts, env, and networks sit in one file. A procedure has to be executed to be understood; a declaration can just be read — by a human or by another agent. In a world where agents build and audit each other's boxes, I'd expect the readable form to win. But that's a forecast, not a verdict: what we can observe today is two vocabularies — imperative and declarative — emerging in parallel for the same per-VM box.

Exhibit 4: the same principle, invented three times

"Free inside, gate at the boundary" isn't only Apple's pattern. The players differ in what they build the boundary out of:

The spatial layer — physical walls. VMs: places the agent simply cannot reach
The semantic layer — judging the meaning of an action. "Is this force push dangerous?" A checkpoint officer instead of a wall
The resource layer — shrinking what's handed over in the first place. Mounts and env: can't leak what you don't hold

Layer	Main implementation	Declared in	Enforced by
Spatial (Apple)	VM boundary, entitlements	entitlements / VM config	kernel, hypervisor
Semantic (Anthropic)	the auto-mode classifier	`autoMode.environment` (prose)	a classifier LLM
Resource (compose)	mounts / env / networks	compose.yaml	VM configuration

"Main" because nobody stays in one layer: Anthropic also ships a process-level spatial layer (Seatbelt on macOS, bubblewrap on Linux, with a proxy-enforced domain allowlist — strikingly similar to the egress setup above). It's an OS-process wall, though; a per-VM kernel wall is a harder material, and that's Apple's turf.

The semantic layer deserves a note. Claude Code's auto-mode routes every tool call through a classifier that blocks only the irreversible, destructive, or out-of-environment. Its boundary is declared in prose ("Source control: github.example.com/acme-corp"), and its precedence ends with explicit user intent: saying "force push this branch" clears a soft block. Conversational context becomes part of authorization — something a VM or an entitlement can't do in principle. Conversely, a probabilistic classifier can't hard-limit the blast radius of arbitrary code execution. Only the spatial layer can.

So the "capability manifest" has been invented three times — as entitlements, as prose, as compose.yaml — and the three don't compete. They stack, like defense in depth. They already interlock in one concrete place: auto-mode's built-in rules (dump them with claude auto-mode defaults) block launching an unsupervised agent loop only when it runs "without sandbox isolation AND without a per-action approval/monitor gate." Declare the spatial layer, and the semantic layer steps aside. The sandbox from Exhibit 3 satisfies exactly that condition — via a compose file.

Verdict

Question	Answer
Are the benchmark downsides real?	✅ Real (my earlier measurements stand)
Are the "agent box" parts all shipped?	✅ per-VM, mcpbridge + ACP, host-side models
Can you build the box today?	✅ compose vocabulary + a real autonomous end-to-end run
Has anyone else made the same choice?	✅ Docker Sandboxes, from the opposite starting point
Has Apple said "this is an agent box"?	❌ Never, anywhere. That part is my reading

The parts exist, the philosophy matches, and the box demonstrably works. What's missing is Apple saying so. Circumstantial evidence everywhere; the suspect remains silent.

So, predictions — ordered by my confidence, so this reading can be scored later. If these miss, the title was just my imagination:

apple/container ships per-container egress control. This is the big one. Docker Sandboxes already has native allowlists, and there's an open Discussion asking for network isolation. If two years pass with nothing, discard this whole post
mcpbridge escapes Xcode. An MCP→XPC gate is far too general-purpose to stay a single IDE's feature
Container machines grow agent-workspace features. A box you let agents experiment in badly needs "undo": Docker Sandboxes' save/reset is exactly that. If snapshots/rollback land on container machines, that's the tell
A first-party API connecting Foundation Models to tools running in containers — Apple wiring up its own "models on the host, tools in the box" split
Attestation for agent runs: a verifiable proof that this artifact was produced inside that box (a cousin of GitHub's Artifact Attestations). Far off, but it's the natural endpoint of the PCC lineage — proof by structure, not trust

Honest caveats

Apple has shipped host-side agents with gated tools (mcpbridge/ACP). Running the agent inside the VM is my extrapolation; I verified that it works, not that Apple intends it
The benchmark downsides have not gone away. I still don't recommend moving your dev stack (see the measurements); this post is about a different objective, not revised numbers
The VM protects the host. Whatever you bring inside — the mounted ./work, the token — is inside the blast radius. A manifest declares what you hand over; it doesn't protect what you've handed

Summary

Apple container's "inexplicable" design becomes coherent the moment the box is for untrusted code rather than for your dev stack
The parts — per-VM boundaries, mcpbridge (MCP→XPC), ACP, host-side models — sit squarely in the PCC lineage of structure over trust
The vocabulary to build such a box already exists: a compose file works as an agent's capability manifest, and a real agent completed a task fully autonomously inside one
The same principle now exists at three layers — spatial, semantic, resource — and they stack rather than compete
The scoreboard: whether apple/container ships per-container egress control

Models will keep getting smarter on their own. The contest is moving to the outside: what you hand an agent, how far you let it reach, how you check what it did. Apple writes that in entitlements, Anthropic writes it in prose, and the container world writes it in ten-year-old compose files. The next fight is over how the box gets declared.

If you can refute any prediction on the list, I genuinely want to hear it — comments here or wherever you found this.

Your Claude Code MCP servers are quietly costing you gigabytes of RAM

yukihiro amadatsu — Fri, 17 Jul 2026 10:31:09 +0000

日本語版は Zenn にあります: Claude Code の MCP サーバー、実はメモリ数GB食ってますよ

The `.mcp.json` you probably have

If you've wired MCP servers into Claude Code (or Cursor), yours probably looks
like this:

{ "mcpServers": { "terraform": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "hashicorp/terraform-mcp-server"] } } }

That docker means Docker Desktop is running — resident, all day — to host
this. Open Activity Monitor and look: "Virtual Machine Service for Docker"
alone is over 1 GB, plus the backend and UI processes around it.

Now consider what an MCP server actually does. It only exists during a session,
and even then it's idle ~99% of the time, waiting for a tool call. You're
keeping a gigabyte-class VM warm around the clock for a tool shed that's
almost always asleep.

On macOS 26 you can take that memory back with a one-line swap to Apple's
first-party container runtime:

claude mcp add terraform -- container run -i --rm hashicorp/terraform-mcp-server

That's the whole migration. No Docker Desktop, no extra tooling. I verified
this with Docker Desktop fully quit — zero docker processes alive — and
Claude Code tool calls still going through.

(If this is your first time with Apple's container, install and start the
runtime first — brew install container, then container system start.
Details in the migration section below.)

The rest of this post covers why this workload is the one place Apple
container genuinely wins (I have measurements), where you'll outgrow the raw
command, and the one trap I hit running it for real.

MCP servers are the shape Apple container is good at

In my previous post
I measured Apple container and concluded, honestly, that it's not ready
to be your daily dev environment: every container gets its own VM at ~270–400
MB, and throwaway containers start 4–10× slower than Docker's. For a
multi-service dev stack, those numbers hurt.

But an MCP server inverts every one of those trade-offs:

a few small images, not a stack
alive only during a session, idle nearly all of it
third-party code holding your API tokens — the more isolation, the better

Apple container has no resident VM. Idle host-side cost is roughly 50 MB,
and the MCP server's VM exists only while your session does. Docker Desktop's
shared VM runs 1.4–2.1 GB all the time for the same job. For a tool shed
that's 99% idle, that's a bad rent.

And per-VM isolation is not just a talking point here. An MCP server is
somebody else's code holding your GitHub token. On Apple container, each
server gets its own VM — a materially stronger wall than Docker containers
sharing one kernel.

Migrating (about a minute)

Prerequisites: macOS 26 on Apple silicon, plus one-time runtime setup.

brew install container   # or grab it from github.com/apple/container/releases
container system start

Then swap the registration:

claude mcp remove terraform
claude mcp add terraform -- container run -i --rm hashicorp/terraform-mcp-server

Open a new session, check /mcp shows connected, call a tool once. Images are
pulled automatically on first connect.

Docker Desktop running, one container active: the "Virtual Machine Service for Docker" alone is 1.13 GB, and the backend/UI family pushes the total past 1.4 GB. (Recent Docker Desktop versions can park the VM while no containers run — but even then the family keeps ~400 MB resident, measured.)

After quitting Docker Desktop: all that's left is com.docker.vmnetd, a 4.4 MB resident LaunchDaemon.

Apple container running the terraform MCP server: "Virtual Machine Service for container-runtime-linux" at 275 MB plus a few single-digit-MB helpers. The containermanagerd and ContainerMetadataExtractor rows are stock macOS daemons that just happen to match the search — nothing to do with Apple container.

After quitting Docker Desktop, Activity Monitor shows the Docker family
(backend + VM + UI, over 1 GB combined) gone. In its place: one "Virtual
Machine Service for container-runtime-linux" at ~280 MB and a ~20 MB helper —
and only while a session is open.

Where the raw command stops being enough

A bare container run covers exactly one case: a single stdio server with no
secrets. Hit any of the following and it's time to graduate to a compose file.
I'll use opossum, the compose-compatible
orchestrator for Apple container I've been building, but the reasoning is
tool-agnostic.

1. A server that needs a token

With raw commands, the token ends up inline in .mcp.json — a file that's
often project-scoped and committed. That's an incident waiting to happen. With
compose, the token lives in a git-ignored .env, and .mcp.json carries only
a command:

// .mcp.json — no token in sight
{ "mcpServers": { "github": {
    "command": "opossum",
    "args": ["-f", "/path/to/mcp-stack/compose.yaml", "run", "--rm", "github"] } } }

# compose.yaml — the token is injected from .env next to this file
  github:
    image: ghcr.io/github/github-mcp-server
    environment:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN:-}
    profiles: ["stdio"]   # not started by `up`; runs only when invoked

.env resolves relative to the compose file, so it works no matter which
directory your MCP client launches from.

2. Several servers

At three or four servers you start wanting bulk image updates
(opossum pull), a single config listing (opossum config), and one file
that is your toolbox.

3. An HTTP-transport server

Streamable-HTTP MCP servers are long-running services — that's up / down /
logs territory, not run --rm:

opossum -f mcp-stack/compose.yaml up

// .mcp.json just points at the URL
{ "mcpServers": { "terraform-http": { "url": "http://localhost:8080/mcp" } } }

One gotcha: if the server binds its default 127.0.0.1, the published port
can't reach it. Bind all interfaces — e.g. --transport-host 0.0.0.0 for
terraform-mcp-server; other servers have an equivalent flag.

A working example with all three patterns in one file is at
examples/mcp-stack.

The trap I actually hit

"Connected, but every tool call fails." A stdio connection runs over
stdin/stdout and never touches the network, so the connection looks perfectly
healthy even when the container's outbound networking is dead. Tools fail only
at the moment they hit an external API — and the error comes back wearing an
innocent face like "provider not found", nothing that says network.

In my case, outbound traffic on the default network died after the runtime had
been up for several days. The triage is one line:

container run --rm alpine ping -c1 1.1.1.1

If that fails, container system stop && container system start recovers it.
If you use opossum, opossum doctor runs this probe as part of a one-shot
environment check.

Honest caveats

Session start pays ~1 second of VM boot. Tool calls after connection are unaffected.
Xcode users get first-party MCP integration (Xcode 27 supports MCP natively). This post is for people who live outside Xcode — Claude Code, Cursor, and friends.
I still don't recommend migrating your dev stack itself. The measurements in the previous post stand. MCP servers are the first real-world instance of the one shape that post said Apple container is good at: small, occasional, idle.

Summary

On macOS 26, changing docker to container in .mcp.json runs your MCP servers without Docker Desktop
The MCP workload (small, idle, credential-holding) matches Apple container's strengths exactly
Graduate to compose when you hit tokens, server sprawl, or HTTP transport — until then the raw command is enough
If tools fail while showing connected, ping 1.1.1.1 from a container first

Agent toolboxes only grow from here, and the shed they live in should be light
and isolated. Models keep getting smarter on their own — the leverage is in
the tooling around them, and there's no reason that tooling should cost you
gigabytes of always-on RAM.

If you run your MCP setup on Apple container, I'd love to hear how it went —
comments or issues both work.
"Here's what happened with my config" is plenty.

Apple's container hit 1.0. Should it be your dev environment yet? I measured.

yukihiro amadatsu — Tue, 14 Jul 2026 14:56:57 +0000

Introduction

Apple's container runtime reached 1.0
in June (1.1.0, a bug-fix patch, is current as I write), and on macOS 26
containers can finally talk to each other — which is the last piece needed to
run a multi-service dev stack. The pieces are, genuinely, all here now.

So I wanted an honest answer to the practical question: should you switch your
daily dev environment to it today? I measured two things that decide that —
compatibility (does your docker-compose.yml run?) and performance (is it
actually pleasant to live in?). The short version, up front, so I'm not burying
the lede:

Compatibility is real — about half of the compose files I tried ran
unmodified, and ~60% within a one-line fix. But performance is behind
today, and for a normal multi-service dev stack that's the part you feel.
If you want a Docker Desktop replacement right now, Docker itself, Colima,
or OrbStack (the established alternatives — all built on the same shared-VM
model as Docker) are the pragmatic picks. Apple container is the better
choice today in exactly one shape: a small image or two, run occasionally.
I'd watch it closely — but I wouldn't move my main dev stack onto it yet.

Here's the data behind that.

Part 1 — Compatibility: better than I expected

I took Docker's own
awesome-compose repository — the
official collection of sample compose projects (WordPress, React+Express+Mongo,
Spring+Postgres, Prometheus+Grafana, …) — and ran 29 of its samples,
unmodified, on Apple container. An alphabetical slice, no cherry-picking:
every sample from nextcloud-postgres through wordpress-mysql.

Setup

Apple's container is a runtime, not an orchestrator: it has no compose
subcommand, no dependency ordering, no service discovery. For that I used
opossum, a small compose-like
orchestrator for Apple container that I've been building. It reads your
existing compose.yaml / docker-compose.yml and gives you the familiar
verbs — up, ps, logs, exec, down:

brew install suruseas/opossum/opossum
container system start                     # start the runtime (once)
sudo container system dns create opossum   # one-time: DNS domain so services
                                           # resolve each other by name

Method: macOS 26 on Apple silicon, Apple container 1.0. For each sample:
cd in, opossum up, give it ~90 seconds to come up, check ps and logs,
categorize, down, next. Every failure got a second look to find the actual
root cause — the interesting part is whose fault each one was.

Note: container 1.1.0 shipped after the survey; it's a bug-fix release
(UDS mounts, a cp fix) and doesn't change these compatibility results. The
Part 2 performance numbers were measured on 1.1.0.

The results

Outcome	Count
Ran as-is — zero changes	14	WordPress, React+Express+MySQL/Mongo, Spring, nginx+Go+MySQL, pgAdmin, Kafka, …
Ran after a one-line compose change	4	3× Postgres data dir, 1× amd64-only image
Broken upstream — the sample itself has rotted	5	would fail regardless of runtime
Can't run by design	3	Docker socket ×2, Linux kernel access ×1
Environment / setup	2	placeholder path, host port already taken
Build outlasted my timeout	1	a 10–15 min Rust→Wasm build (no errors — I got impatient)

The headline: 18 of the 29 samples run on Apple's runtime today, 14 of
them without touching a single line. And of the 11 that didn't, not one
failed because of the runtime's container execution or networking — every
failure traced to the sample itself, to Docker-specific host features, or to my
environment.

Let's look at the categories, because a couple of them teach you something
about how Apple's runtime actually differs from Docker.

The one-line fixes (and what they reveal)

Postgres refuses its data volume (3 samples)

nextcloud-postgres, nginx-golang-postgres, and spring-postgres all define
the classic:

volumes:
  - db-data:/var/lib/postgresql/data

On Docker this works. On Apple container Postgres dies with "initdb: error:
directory exists but is not empty". Why: the runtime mounts a named volume as
a real ext4 mount point — which contains lost+found — and initdb refuses a
non-empty directory. Docker's volumes don't surface that detail.

The one-line fix is the same one you'd use on any bare-metal mount:

environment:
  PGDATA: /var/lib/postgresql/data/pgdata   # a subdirectory of the mount

This pattern is everywhere in self-hosted app composes (Gitea, Nextcloud,
…), so opossum detects it at up time and prints exactly that suggested fix.
MySQL and MariaDB tolerate the mount point, which is why the WordPress and
MySQL samples sailed through.

amd64-only images (1 sample)

nginx-nodejs-redis uses redismod, an image published only for x86-64. The
fix is the same line you'd add for Docker on Apple silicon:

platform: linux/amd64

opossum passes the platform through and automatically enables Rosetta
translation for the container, so the x86-64 image runs on the arm64 VM.

The ones that were broken before I arrived (5 samples)

This was the fun discovery. Five samples fail on any runtime today, because
they pin nothing and the world moved:

nginx-flask-mysql — Flask backend crashes with ImportError: cannot import name 'url_quote' from 'werkzeug.urls': the famous Flask/Werkzeug 2.1 break, hit because the sample doesn't pin Werkzeug. (The nginx "host not found in upstream" error that follows is just the dead backend cascading.)
prometheus-grafana — the unpinned prom/prometheus image now rejects the sample's api_version: v1 Alertmanager config.
nginx-wsgi-flask, react-rust-postgres, vuejs — pip install / cargo / yarn global add failures during build, all dependency rot.

I went in expecting to find runtime incompatibilities; instead I found a small
museum of what happens to unmaintained compose files after a few years. If
your own stack pins its images and dependencies, this whole category doesn't
apply to you.

Can't run by design (3 samples)

Full honesty, because this is where the model genuinely differs:

portainer, traefik-golang bind-mount /var/run/docker.sock — they manage/inspect Docker. Apple's runtime has no Docker socket; anything whose job is talking to the Docker daemon is out.
wireguard needs NET_ADMIN plus the host's kernel modules (/lib/modules). There's no shared Linux host kernel to reach into — each container has its own micro-VM. (Docker Desktop on a Mac can't satisfy the host-path part either.)

If your compose file is "a normal app + database + cache", none of this
touches you. If it's host-level infrastructure tooling, stay on Docker.

The rest

plex ships a placeholder bind path (/media/your/plex/path) you're meant to edit — environment, not compatibility.
pihole-cloudflared-DoH wants host port 53, which my Mac was already using. (opossum checks published ports up front and names the conflict instead of failing mid-startup.)
wasmedge-mysql-nginx compiles Rust to WebAssembly inside the build — 10–15 minutes of cargo build. It was progressing without errors when my 90-second patience ran out, so it goes in the "almost certainly fine" pile, not the failure pile.

Gotchas beyond this sample set

Two more differences worth knowing before you try your own stack, found in
wider testing:

Fresh volumes mount empty. Docker pre-fills a brand-new named/anonymous volume from the image's contents at that path; Apple container doesn't. That breaks the beloved - /app/node_modules trick. opossum replicates Docker's seeding behavior itself, so this pattern works — but it's a real runtime difference you'd hit with raw container commands.
cgroup-sniffing JVMs crash. Elasticsearch 7.x's bundled JDK reads the host cgroup to size its heap, and the micro-VM doesn't expose the mount it expects — it dies at launch before any config applies. A runtime/JDK incompatibility with no workaround I know of.
A named volume can only be attached to one running container. Apple container attaches a named volume as an exclusive block device to a single VM; the second container that mounts the same volume fails with a cryptic VZErrorDomain … storage device attachment is invalid. Docker allows sharing, and the common "app + nginx share an assets volume" pattern relies on it — on Apple container, use a bind mount (a host directory) for data that two services must see at once. (opossum detects this case too and warns at up time.)

Part 2 — Performance: this is where it's behind today

Compatibility was the good news. Performance is the honest bad news, and it's
the part you actually feel day to day. All numbers below are from one machine
(M2, 16 GB; Apple container 1.1.0, Docker Desktop / Engine 29.5.3) —
reproduce them yourself; the point is the shape, not the third decimal.

Memory doesn't work the way the idle number suggests. The headline "~50 MB
idle vs Docker's multi-GB VM" is true, but it's only the start of the story,
because the two runtimes allocate memory completely differently. Apple container runs one VM
per container, and that cost is exact and verifiable: an idle nginx:alpine
VM has a ~270 MB physical footprint (a bare alpine idles at ~235–255 MB —
that's the fixed guest-kernel floor, and lowering the -m cap doesn't lower
it), it scales dead linearly (six containers = six VMs ≈ 1.6 GB + ~20 MB of
helpers each), and macOS genuinely attributes the guest's memory to the VM
process — I held 300 MB of incompressible data inside one and watched its
footprint grow by exactly that (254 M → 557 M).

Docker runs one shared VM all containers draw from — and measuring it
honestly has a trap I fell into myself: Docker's guest memory doesn't show up
under any com.docker.* process. It lives in a process Activity Monitor calls
"Virtual Machine Service for Docker" (both runtimes use Apple's
Virtualization framework), and the same 300 MB test grows that process by
exactly 0.3 GB (1.1 G → 1.4 G). Sum it correctly and Docker looks like this:

	Apple `container` (exact, linear)	Docker Desktop (elastic base)
Nothing running	~50 MB	~1.4–2.1 GB warm (helpers + VM; shrinks only over long idle)
Each added small container	+~290 MB	~+0 (six more nginx moved it ~10 MB)
Heavy workload ends	VM freed with the container	VM keeps its high-water mark

So the honest memory verdict is subtler than either camp's pitch: Apple wins
clearly when idle or running 1–2 things; at a typical 5–10 service stack the
totals are comparable (Apple ~1.5–3 GB of exact, linear cost vs Docker's
~1.4–2.1 GB elastic base); past ~10 services Docker's shared pool wins. The
crossover lands anywhere from ~2 to ~7 containers depending on how warm
Docker's VM is. The per-VM model's real upside is isolation (a runaway
container can't starve its neighbors) and predictability — you can point at
the exact process each container costs you.

What actually decides the dev-stack question is speed, not memory. Same
machine:

	Docker Desktop	Apple `container`
Single container start	~0.19 s	~0.81 s (boots a fresh micro-VM)
10× `run --rm`, sequential	2.1 s	8.3 s (~4× slower)
10× `run --rm`, in parallel	0.75 s	7.6 s (~10× — a shared daemon parallelizes, per-VM doesn't)
First build in a session	warm	+~6 s builder-VM cold start
Bind-mount small-file I/O	slow	slightly slower (same host↔VM model)

The throwaway-container gap is architectural — one lightweight VM per container —
so it won't simply close with a point release. For anything that churns
short-lived containers (test suites, CI-like loops) it's a real tax today.

The pieces are all there in Apple container. But on this performance profile,
a daily multi-service dev stack is not where it wins yet — that's the
Part 2 conclusion. (Full method and the wider comparison.)

The verdict: when to pick it (and when not to, yet)

Your situation	Today's pick
Daily multi-service dev stack (app + DB + cache + …)	Docker / Colima / OrbStack — faster where it counts (memory is roughly comparable at this scale)
Churning lots of short-lived containers (tests)	Docker — per-VM start cost hurts here
Needs `docker.sock`, `NET_ADMIN`, host kernel	Docker — Apple `container` can't, by design
A small image or two, run occasionally, mostly idle	Apple `container` — genuinely lighter, cleaner isolation, no license
You want per-container VM isolation and no always-on VM	Apple `container` — the one thing nothing else here gives you

That's the honest 2026 read: the 1.0 pieces are in place, compatibility is
real, but the performance envelope means Docker and the established alternatives
are the practical choice for a normal dev environment right now. Apple
container's current sweet spot is narrow — small, occasional, idle-most-of-the-
time workloads — and its structural advantage (VM-per-container isolation with no
resident VM) is worth watching as the runtime matures. I'd revisit this in a few
releases; I wouldn't move my main stack over today.

So if not docker compose, what is it for?

"Not yet for your main dev stack" sounds like a verdict with no upside, but
flip the measured properties around and a clear niche appears: near-zero cost
at idle, a VM boundary around every container, ~1s to start one. In other
words, small things, run occasionally, isolated.

The toolbox for coding agents (MCP servers). The MCP servers you wire into Claude Code and friends are a handful of small images that run only during a session and idle the rest of the time — and they're third-party code holding your API tokens, so per-VM isolation is a real benefit. On my machine, claude mcp add terraform -- container run -i --rm hashicorp/terraform-mcp-server is the whole setup, and it works with Docker Desktop not even installed.
A sandbox for AI agents. For running agent-generated code autonomously, a disposable VM boundary is one step stronger than a kernel-sharing container. Line up WWDC26's announcements — MCP support in Xcode 27, Container machines — and Apple itself seems to be looking in this direction.

I'll cover the verification and setup for these in follow-up posts.

Try it yourself — it's safe next to Docker

If you want to see where your own compose lands, it's three commands, and it
won't touch your Docker state (Apple's runtime keeps entirely separate images,
containers, and volumes; opossum down -v only ever removes its own):

brew install suruseas/opossum/opossum
container system start                     # start the runtime
sudo container system dns create opossum   # once: DNS domain for name resolution

cd your-project        # with its existing docker-compose.yml
opossum config         # optional: preview which fields (if any) get ignored
opossum up

If docker compose already built your images, opossum up --from-docker
imports them and starts without rebuilding — it changes the first-run
experience considerably. And if something misbehaves, opossum doctor
diagnoses the environment (runtime, DNS, network, builder) and tells you the
fix.

Repo: https://github.com/suruseas/opossum

Closing notes

I'll keep expanding this investigation of Apple container. If you re-run the
performance numbers on different hardware and get different results, I'd love
to hear about it. And if you point opossum up at a real compose file and
something breaks, please tell me — in the comments or in an
issue.

This post is also available in Japanese: Zenn version

I ran 29 real docker-compose projects on Apple's container runtime. Here's what broke

yukihiro amadatsu — Tue, 07 Jul 2026 14:51:59 +0000

Docker Desktop keeps a ~7.8 GB Linux VM provisioned the entire time it's
running — even when zero containers are up. Apple's new
container runtime idles at ~58 MB of
helper processes and only spends memory while a container actually runs, because
it boots a lightweight VM per container, on demand. It hit 1.0 in June, and on
macOS 26 containers can finally talk to each other, which makes multi-service
dev stacks possible.

So the question stopped being "is it interesting?" and became: is it
compatible enough to run the docker-compose.yml files people actually have?

Instead of guessing, I measured. I took Docker's own
awesome-compose repository — the
official collection of sample compose projects (WordPress, React+Express+Mongo,
Spring+Postgres, Prometheus+Grafana, …) — and ran 29 of its samples,
unmodified, on Apple container. An alphabetical slice, no cherry-picking:
every sample from nextcloud-postgres through wordpress-mysql.

Here's the breakdown, and — more useful — why each failure failed.

Setup

brew install suruseas/opossum/opossum
container system start                     # start the runtime (once)
sudo container system dns create opossum   # one-time: DNS domain so services
                                           # resolve each other by name

The results

Outcome	Count
✅ Ran as-is — zero changes	14	WordPress, React+Express+MySQL/Mongo, Spring, nginx+Go+MySQL, pgAdmin, Kafka, …
🔧 Ran after a one-line compose change	4	3× Postgres data dir, 1× amd64-only image
🏗️ Broken upstream — the sample itself has rotted	5	would fail regardless of runtime
🚫 Can't run by design	3	Docker socket ×2, Linux kernel access ×1
⚙️ Environment / setup	2	placeholder path, host port already taken
🐌 Build outlasted my timeout	1	a 10–15 min Rust→Wasm build (no errors — I got impatient)

The headline: 18 of 29 real-world stacks run on Apple's runtime today, 14 of
them without touching a single line. And of the 11 that didn't, not one
failed because of the runtime's container execution or networking — every
failure traced to the sample itself, to Docker-specific host features, or to my
environment.

Let's look at the categories, because a couple of them teach you something
about how Apple's runtime actually differs from Docker.

The one-line fixes (and what they reveal)

Postgres refuses its data volume (3 samples)

nextcloud-postgres, nginx-golang-postgres, and spring-postgres all define
the classic:

volumes:
  - db-data:/var/lib/postgresql/data

The one-line fix is the same one you'd use on any bare-metal mount:

environment:
  PGDATA: /var/lib/postgresql/data/pgdata   # a subdirectory of the mount

amd64-only images (1 sample)

nginx-nodejs-redis uses redismod, an image published only for x86-64. The
fix is the same line you'd add for Docker on Apple silicon:

platform: linux/amd64

opossum passes the platform through and automatically enables Rosetta
translation for the container, so the x86-64 image runs on the arm64 VM.

The ones that were broken before I arrived (5 samples)

This was the fun discovery. Five samples fail on any runtime today, because
they pin nothing and the world moved:

nginx-flask-mysql — Flask backend crashes with ImportError: cannot import name 'url_quote' from 'werkzeug.urls': the famous Flask/Werkzeug 2.1 break, hit because the sample doesn't pin Werkzeug. (The nginx "host not found in upstream" error that follows is just the dead backend cascading.)
prometheus-grafana — the unpinned prom/prometheus image now rejects the sample's api_version: v1 Alertmanager config.
nginx-wsgi-flask, react-rust-postgres, vuejs — pip install / cargo / yarn global add failures during build, all dependency rot.

Can't run by design (3 samples)

Full honesty, because this is where the model genuinely differs:

portainer, traefik-golang bind-mount /var/run/docker.sock — they manage/inspect Docker. Apple's runtime has no Docker socket; anything whose job is talking to the Docker daemon is out.
wireguard needs NET_ADMIN plus the host's kernel modules (/lib/modules). There's no shared Linux host kernel to reach into — each container has its own micro-VM. (Docker Desktop on a Mac can't satisfy the host-path part either.)

If your compose file is "a normal app + database + cache", none of this
touches you. If it's host-level infrastructure tooling, stay on Docker.

The rest

plex ships a placeholder bind path (/media/your/plex/path) you're meant to edit — environment, not compatibility.
pihole-cloudflared-DoH wants host port 53, which my Mac was already using. (opossum checks published ports up front and names the conflict instead of failing mid-startup.)
wasmedge-mysql-nginx compiles Rust to WebAssembly inside the build — 10–15 minutes of cargo build. It was progressing without errors when my 90-second patience ran out, so it goes in the "almost certainly fine" pile, not the failure pile.

Gotchas beyond this sample set

Two more differences worth knowing before you try your own stack, found in
wider testing:

Fresh volumes mount empty. Docker pre-fills a brand-new named/anonymous volume from the image's contents at that path; Apple container doesn't. That breaks the beloved - /app/node_modules trick. opossum replicates Docker's seeding behavior itself, so this pattern works — but it's a real runtime difference you'd hit with raw container commands.
cgroup-sniffing JVMs crash. Elasticsearch 7.x's bundled JDK reads the host cgroup to size its heap, and the micro-VM doesn't expose the mount it expects — it dies at launch before any config applies. A runtime/JDK incompatibility with no workaround I know of.

And the trade-offs cut both ways — this isn't "Docker but better":

	Docker Desktop	Apple `container`
Idle memory	~373 MB host procs + ~7.8 GB VM	~58 MB, no always-on VM
Single container start	~0.19 s	~0.81 s (boots a fresh micro-VM)
Bind-mount small-file I/O	slow	slightly slower (same host↔VM model)
Isolation	shared VM kernel	per-container VM
License	paid for larger orgs	open source

Docker still wins if you churn many short-lived containers or hammer bind
mounts. Apple's runtime wins on footprint and isolation. (Numbers from one
machine — method and caveats here.)

Try it on your own compose file

The whole experiment, reproduced on your project, is three commands:

brew install suruseas/opossum/opossum
cd your-project        # with its existing docker-compose.yml
opossum up

It's safe to try next to Docker: Apple's runtime keeps entirely separate
images, containers, and volumes, so your Docker state isn't touched. opossum config shows you up front which compose fields (if any) it will ignore, and
down cleans everything up.

Based on this sample: 48% of real-world stacks ran with zero changes, 62%
with at most one line — and the failures concentrated in stale samples and
Docker-specific tooling, not in the runtime.

Repo: https://github.com/suruseas/opossum — and I'd genuinely like to grow
this survey: if you run opossum up on a real compose file and it breaks,
tell me what broke (here or in an issue). The failure catalog is the product.

I ran 29 real docker-compose projects on Apple's container runtime. Here's what broke

yukihiro amadatsu — Tue, 07 Jul 2026 14:47:11 +0000

So the question stopped being "is it interesting?" and became: is it
compatible enough to run the docker-compose.yml files people actually have?

Here's the breakdown, and — more useful — why each failure failed.

Setup

brew install suruseas/opossum/opossum
container system start                     # start the runtime (once)
sudo container system dns create opossum   # one-time: DNS domain so services
                                           # resolve each other by name

The results

Outcome	Count
✅ Ran as-is — zero changes	14	WordPress, React+Express+MySQL/Mongo, Spring, nginx+Go+MySQL, pgAdmin, Kafka, …
🔧 Ran after a one-line compose change	4	3× Postgres data dir, 1× amd64-only image
🏗️ Broken upstream — the sample itself has rotted	5	would fail regardless of runtime
🚫 Can't run by design	3	Docker socket ×2, Linux kernel access ×1
⚙️ Environment / setup	2	placeholder path, host port already taken
🐌 Build outlasted my timeout	1	a 10–15 min Rust→Wasm build (no errors — I got impatient)

Let's look at the categories, because a couple of them teach you something
about how Apple's runtime actually differs from Docker.

The one-line fixes (and what they reveal)

Postgres refuses its data volume (3 samples)

nextcloud-postgres, nginx-golang-postgres, and spring-postgres all define
the classic:

volumes:
  - db-data:/var/lib/postgresql/data

The one-line fix is the same one you'd use on any bare-metal mount:

environment:
  PGDATA: /var/lib/postgresql/data/pgdata   # a subdirectory of the mount

amd64-only images (1 sample)

nginx-nodejs-redis uses redismod, an image published only for x86-64. The
fix is the same line you'd add for Docker on Apple silicon:

platform: linux/amd64

opossum passes the platform through and automatically enables Rosetta
translation for the container, so the x86-64 image runs on the arm64 VM.

The ones that were broken before I arrived (5 samples)

This was the fun discovery. Five samples fail on any runtime today, because
they pin nothing and the world moved:

nginx-flask-mysql — Flask backend crashes with ImportError: cannot import name 'url_quote' from 'werkzeug.urls': the famous Flask/Werkzeug 2.1 break, hit because the sample doesn't pin Werkzeug. (The nginx "host not found in upstream" error that follows is just the dead backend cascading.)
prometheus-grafana — the unpinned prom/prometheus image now rejects the sample's api_version: v1 Alertmanager config.
nginx-wsgi-flask, react-rust-postgres, vuejs — pip install / cargo / yarn global add failures during build, all dependency rot.

Can't run by design (3 samples)

Full honesty, because this is where the model genuinely differs:

portainer, traefik-golang bind-mount /var/run/docker.sock — they manage/inspect Docker. Apple's runtime has no Docker socket; anything whose job is talking to the Docker daemon is out.
wireguard needs NET_ADMIN plus the host's kernel modules (/lib/modules). There's no shared Linux host kernel to reach into — each container has its own micro-VM. (Docker Desktop on a Mac can't satisfy the host-path part either.)

If your compose file is "a normal app + database + cache", none of this
touches you. If it's host-level infrastructure tooling, stay on Docker.

The rest

plex ships a placeholder bind path (/media/your/plex/path) you're meant to edit — environment, not compatibility.
pihole-cloudflared-DoH wants host port 53, which my Mac was already using. (opossum checks published ports up front and names the conflict instead of failing mid-startup.)
wasmedge-mysql-nginx compiles Rust to WebAssembly inside the build — 10–15 minutes of cargo build. It was progressing without errors when my 90-second patience ran out, so it goes in the "almost certainly fine" pile, not the failure pile.

Gotchas beyond this sample set

Two more differences worth knowing before you try your own stack, found in
wider testing:

Fresh volumes mount empty. Docker pre-fills a brand-new named/anonymous volume from the image's contents at that path; Apple container doesn't. That breaks the beloved - /app/node_modules trick. opossum replicates Docker's seeding behavior itself, so this pattern works — but it's a real runtime difference you'd hit with raw container commands.
cgroup-sniffing JVMs crash. Elasticsearch 7.x's bundled JDK reads the host cgroup to size its heap, and the micro-VM doesn't expose the mount it expects — it dies at launch before any config applies. A runtime/JDK incompatibility with no workaround I know of.

And the trade-offs cut both ways — this isn't "Docker but better":

	Docker Desktop	Apple `container`
Idle memory	~373 MB host procs + ~7.8 GB VM	~58 MB, no always-on VM
Single container start	~0.19 s	~0.81 s (boots a fresh micro-VM)
Bind-mount small-file I/O	slow	slightly slower (same host↔VM model)
Isolation	shared VM kernel	per-container VM
License	paid for larger orgs	open source

Docker still wins if you churn many short-lived containers or hammer bind
mounts. Apple's runtime wins on footprint and isolation. (Numbers from one
machine — method and caveats here.)

Try it on your own compose file

The whole experiment, reproduced on your project, is three commands:

brew install suruseas/opossum/opossum
cd your-project        # with its existing docker-compose.yml
opossum up

Based on this sample: 48% of real-world stacks ran with zero changes, 62%
with at most one line — and the failures concentrated in stale samples and
Docker-specific tooling, not in the runtime.

Run your docker-compose.yml on Apple's container runtime

yukihiro amadatsu — Mon, 06 Jul 2026 16:49:45 +0000

If you develop on a Mac and reach for docker compose to spin up a multi-service
stack, you might like opossum — a small,
Docker Compose–like orchestrator for Apple's container
runtime on macOS 26.

The pitch is simple: point it at a docker-compose.yml you already have and run
opossum up. The commands and mental model are the same ones you already know —
up, ps, logs, down — but everything runs on Apple's native container
runtime (a lightweight VM per container) instead of Docker Desktop.

Let me show you.

Install

opossum ships as a Homebrew formula:

brew install suruseas/opossum/opossum

Two one-time steps (Apple container prerequisites):

container system start                    # start the runtime
sudo container system dns create opossum  # register a local DNS domain so
                                          # services can find each other by name

That's it. (Requires macOS 26 on Apple silicon, since the runtime's
container-to-container networking relies on macOS 26 features.)

Just try it on a project you already have

The fastest way to get a feel for it: cd into a directory you already run with
docker compose and run opossum up. For a lot of stacks it just works — same
file, same command, nothing to change. (opossum finds your compose.yaml or
docker-compose.yml automatically.)

And it's safe to try side by side with Docker. opossum drives Apple's
container runtime, which is entirely separate from Docker — its own images,
containers, and volumes — so running opossum up won't touch your Docker
containers or data.

To follow along in this post, here's a tiny stack:

services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    depends_on:
      - redis
  redis:
    image: redis:7

`opossum up`

$ opossum up
Creating network intro-net
Starting redis (redis:7)
redis.intro.opossum
Starting web (nginx:alpine)
web.intro.opossum
  ↳ web on the host: localhost:8080

It starts the services in dependency order (redis before web, because web
depends_on it) and tells you where to reach a published service from the host —
localhost:8080.

`opossum ps`

Same output you'd expect from docker compose ps:

$ opossum ps
SERVICE  CONTAINER            IMAGE         IP            PORTS                 STATUS
redis    redis.intro.opossum  redis:7       192.168.67.2  -                     running
web      web.intro.opossum    nginx:alpine  192.168.67.3  0.0.0.0:8080->80/tcp  running

Open http://localhost:8080 in your browser (or curl it) and you get nginx:

$ curl -s http://localhost:8080/ | head -4
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>

Services find each other by name

Just like Compose, peers reach each other by their service name over the
project's network. From inside the web container, redis resolves:

$ opossum exec web sh -c "getent hosts redis"
...  redis.intro.opossum  redis

So your app connects to redis:6379 — no IPs, no hardcoding.

`opossum logs` and `opossum stats`

Follow logs like usual:

$ opossum logs redis
...
1:M 06 Jul 2026 16:43:09.983 * Ready to accept connections tcp

And there's a docker stats–style live view of resource usage per service:

$ opossum stats --no-stream
Container ID         Cpu %  Memory Usage          Net Rx/Tx             Block I/O             Pids
redis.intro.opossum  0.74%  29.91 MiB / 1.00 GiB  16.18 KiB / 0.57 KiB  25.68 MiB / 0.00 KiB  6
web.intro.opossum    0.00%  15.48 MiB / 1.00 GiB  15.15 KiB / 2.14 KiB  9.94 MiB / 4.00 KiB   6

`opossum down`

$ opossum down
Stopping web
Stopping redis

Tears everything down in reverse order and removes the project network. Add -v
to also drop named volumes.

It's almost the same as docker compose

If you know Compose, you already know opossum. The everyday commands map 1:1:

You'd type in Compose	With opossum
`docker compose up`	`opossum up`
`docker compose ps`	`opossum ps`
`docker compose logs -f web`	`opossum logs web -f`
`docker compose exec web sh`	`opossum exec -it web sh`
`docker compose down -v`	`opossum down -v`

opossum also has stats, images, pull, build, run, start/stop/
restart/kill, and config — the usual toolbox.

A few honest differences, since it targets Apple's runtime rather than Docker:

One-time setup: the sudo container system dns create opossum step above, which is what makes bare-name service discovery work.
Runtime: it's Apple container (a per-container lightweight VM), not Docker Engine. Compose fields the runtime can't act on (like custom networks: or container_name:) are parsed and warned about, not silently dropped.
macOS 26 + Apple silicon only.

Try it

brew install suruseas/opossum/opossum
cd your-project-with-a-compose-file
opossum up

Repo: https://github.com/suruseas/opossum. If you have a docker-compose.yml
lying around, give opossum up a try and see how far it gets — for a lot of
stacks, the answer is "all the way."

🐢 and 🐇 in My Claude Code Status Line: Now Watching the Week

yukihiro amadatsu — Mon, 11 May 2026 15:45:27 +0000

I recently built a tortoise-and-hare status line for Claude Code that shows whether you're burning tokens faster than a steady pace. That post is here.

Then Anthropic raised the 5h limit but tightened the weekly cap. Suddenly the 7-day limit became the one that actually bites — with the relaxed 5h window, hitting 100% in five hours takes real effort. The weekly cap doesn't.

So I updated the script: 7d gets the full-width tortoise/hare bar, 5h keeps the same logic in a shorter bar on the right:

[Sonnet 4.6] ········🐢···········🐇 7d:105% ⚠️@5/14 | ··🐢··🐇··· 5h:70% ⚠️@18:00

(The 7d:105% is real — that's what I'm seeing right now. Going over 100% means you're into Claude Code's additional usage allowance beyond the base weekly limit. The 🐇 flies off the right edge of the bar when that happens.)

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
FIVE_H_PCT=$(echo "$input" | jq -r '(.rate_limits.five_hour.used_percentage // 0)')
SEVEN_D_PCT=$(echo "$input" | jq -r '(.rate_limits.seven_day.used_percentage // 0)')
FIVE_H_RESETS=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
SEVEN_D_RESETS=$(echo "$input" | jq -r '.rate_limits.seven_day.resets_at // empty')

NOW=$(date +%s)
TZ=Asia/Tokyo  # change to your local timezone
W7=20; W5=10   # bar widths: 7d full, 5h half

make_bar() {
    local actual=$1 ideal=$2 width=$3 bar="" i
    for i in $(seq 0 $((width - 1))); do
        if [ "$i" -eq "$ideal" ] && [ "$i" -eq "$actual" ]; then bar="${bar}🐢🐇"
        elif [ "$i" -eq "$ideal" ]; then bar="${bar}🐢"
        elif [ "$i" -eq "$actual" ]; then bar="${bar}🐇"
        else bar="${bar}·"
        fi
    done
    [ "$actual" -ge "$width" ] && bar="${bar}🐇"
    echo "$bar"
}

# 7-day window (main bar, width=20)
if [ -n "$SEVEN_D_RESETS" ]; then
    REMAINING_7D=$((SEVEN_D_RESETS - NOW))
    RESET_7D_MD=$(date -r "$SEVEN_D_RESETS" "+%m/%d" | awk -F/ '{printf "%d/%d", $1, $2}')
    RESET_7D_TAG="@${RESET_7D_MD}"
    if [ "$REMAINING_7D" -gt 0 ] && [ "$REMAINING_7D" -lt 604800 ]; then
        IDEAL_7D=$(( (604800 - REMAINING_7D) * W7 / 604800 ))
    else
        IDEAL_7D=0
    fi
else
    IDEAL_7D=0; RESET_7D_TAG="@?"
fi
ACTUAL_7D=$(awk "BEGIN {print int($SEVEN_D_PCT * $W7 / 100)}")
BAR_7D=$(make_bar "$ACTUAL_7D" "$IDEAL_7D" "$W7")
[ "$ACTUAL_7D" -gt "$IDEAL_7D" ] && WARN_7D=" ⚠️" || WARN_7D=""
SEVEN_D_DISP=$(printf "%.0f" "$SEVEN_D_PCT")

# 5-hour window (half bar, width=10)
if [ -n "$FIVE_H_RESETS" ]; then
    REMAINING_5H=$((FIVE_H_RESETS - NOW))
    RESET_5H_JST=$(date -r "$FIVE_H_RESETS" "+%H:%M")
    RESET_5H_TAG="@${RESET_5H_JST}"
    if [ "$REMAINING_5H" -gt 0 ] && [ "$REMAINING_5H" -lt 18000 ]; then
        IDEAL_5H=$(( (18000 - REMAINING_5H) * W5 / 18000 ))
    else
        IDEAL_5H=0
    fi
else
    IDEAL_5H=0; RESET_5H_TAG="@?"
fi
ACTUAL_5H=$(awk "BEGIN {print int($FIVE_H_PCT * $W5 / 100)}")
BAR_5H=$(make_bar "$ACTUAL_5H" "$IDEAL_5H" "$W5")
[ "$ACTUAL_5H" -gt "$IDEAL_5H" ] && WARN_5H=" ⚠️" || WARN_5H=""
FIVE_H_DISP=$(printf "%.0f" "$FIVE_H_PCT")

echo "[${MODEL}] ${BAR_7D} 7d:${SEVEN_D_DISP}%${WARN_7D}${RESET_7D_TAG} | ${BAR_5H} 5h:${FIVE_H_DISP}%${WARN_5H}${RESET_5H_TAG}"

W7=20 and W5=10 control bar widths. 18000 = 5 hours in seconds, 604800 = 7 days. Change TZ=Asia/Tokyo at the top to your local timezone.

🐢 and 🐇 in My Claude Code Status Line

yukihiro amadatsu — Thu, 30 Apr 2026 09:28:08 +0000

The Claude Code status line gives you a JSON blob and lets you render whatever you want. Docs here. I made mine an Aesop's fable — borrowing the idea from Rabbit, a presentation tool by Kouhei Sutou that famously races a rabbit against a tortoise to show whether you're on pace.

[Sonnet 4.6] ········🐢····🐇······· 5h:62% ⚠️ | reset 18:00 | 7d:23%

🐢 = where you should be (time elapsed in the 5-hour window).
🐇 = where you actually are (tokens used).
⚠️ = hare is ahead, you're burning too fast.

The point: a raw "62%" means opposite things at hour 1 vs hour 4. Comparing actual pace to ideal pace is what I actually want to know — and the tortoise/hare visual does it at a glance, no mental math.

The script

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
FIVE_H_PCT=$(echo "$input" | jq -r '(.rate_limits.five_hour.used_percentage // 0)')
SEVEN_D_PCT=$(echo "$input" | jq -r '(.rate_limits.seven_day.used_percentage // 0) * 10 | floor | . / 10')
RESETS_AT=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')

if [ -n "$RESETS_AT" ]; then
    REMAINING_SEC=$((RESETS_AT - $(date +%s)))
    RESET_JST=$(TZ=Asia/Tokyo date -r "$RESETS_AT" "+%H:%M")
    RESET_STR=" | reset ${RESET_JST}"
    if [ "$REMAINING_SEC" -gt 0 ] && [ "$REMAINING_SEC" -lt 18000 ]; then
        IDEAL_PCT=$(( (18000 - REMAINING_SEC) * 100 / 18000 ))
    else
        IDEAL_PCT=0
    fi
else
    IDEAL_PCT=0; RESET_STR=""
fi

BAR_WIDTH=20
ACTUAL_POS=$(awk "BEGIN {print int($FIVE_H_PCT * $BAR_WIDTH / 100)}")
IDEAL_POS=$((IDEAL_PCT * BAR_WIDTH / 100))

BAR=""
for i in $(seq 0 $((BAR_WIDTH - 1))); do
    if [ "$i" -eq "$IDEAL_POS" ] && [ "$i" -eq "$ACTUAL_POS" ]; then
        BAR="${BAR}🐢🐇"
    elif [ "$i" -eq "$IDEAL_POS" ]; then BAR="${BAR}🐢"
    elif [ "$i" -eq "$ACTUAL_POS" ]; then BAR="${BAR}🐇"
    else BAR="${BAR}·"
    fi
done

[ "$ACTUAL_POS" -gt "$IDEAL_POS" ] && WARN=" ⚠️" || WARN=""
FIVE_H_DISP=$(echo "$FIVE_H_PCT" | awk '{printf "%.0f", $1}')
echo "[$MODEL] ${BAR} 5h:${FIVE_H_DISP}%${WARN}${RESET_STR} | 7d:${SEVEN_D_PCT}%"

18000 is 5 hours in seconds. Drop TZ=Asia/Tokyo for your local zone.

Install

Save as ~/.claude/statusline.sh, chmod +x it, then in ~/.claude/settings.json:

{
  "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}

Restart Claude Code. Done.

The rabbit-vs-tortoise pacing metaphor is lifted straight from Rabbit (うさぎとかめ). Same idea, different domain — slide timer → token budget.

Stop Counting Prompts — Start Reflecting on AI Fluency

yukihiro amadatsu — Sat, 28 Mar 2026 05:03:07 +0000

"I'm the best at piloting this thing!"

There's a famous line from a Japanese mecha anime — the protagonist screams: 「僕が一番ガンダムをうまく使えるんだ！」 — "I'm the one who can pilot this Gundam the best!"

If you use AI coding tools every day, you've probably felt something similar. That sense of clicking with the AI. Knowing you're getting more out of it than most people around you.

But how do you show that?

"Look at my PR count"? "Check how many lines I generated"? That's not it. Those numbers don't capture the feel of working well with AI. That nagging gap between what you know and what you can prove is what got me started.

My own question, answered

In my previous post, I asked:

yukihiro amadatsu

Mar 18

I Deleted 66% of My AI Coding Guide — Here's What Survived

#ai #programming #productivity #codequality

5 min read

Is your team measuring AI coding productivity by any of these?

Common metric	What it actually rewards
Lines of code generated	Volume targets promote bloat
Number of prompts per session	High count may signal poor instructions, not hard work
Response speed	Penalizes people who think before they ask
Commit count	Easily inflated by splitting work
Number of AI tools adopted	Using ≠ using well

They all measure quantity. But whether you're actually good at working with AI never shows up in volume metrics.

That article laid out three enduring principles: keep things reversible, make intent explicit, verify outputs. AI Fluency is my attempt to turn those into a structured self-reflection — not a score that ranks you, but a mirror that shows you how you collaborate.

Why "Fluency"?

Fluency — like language fluency. When you're fluent, conversation flows naturally. You don't stumble, backtrack, or struggle to express what you mean.

Working with AI has a similar feel. When it's going well, your instructions and the AI's output click, and the work just flows. When it's not, you're stuck in loops of corrections and rework.

AI Fluency tries to visualize that — how naturally you collaborate with AI.

Here's what I built

My result: The Explorer — the type that explores new ways of using AI. Strong in Breadth, with room to grow in Precision.

Full ability sheet: profile.md

Repo: github.com/suruseas/ai-fluency

Also available in Japanese on Qiita.

A Different Yardstick: 5 Axes

By breaking down what "fluency" actually means in practice, I landed on five dimensions:

Axis	What it measures
Context Design	Setting up the environment so the AI can do its best work
Precision	Communicating intent clearly with minimal back-and-forth
Steering	Guiding AI output in the right direction; judging quality
Output	Actually delivering value through AI collaboration
Breadth	Using AI's capabilities across diverse tasks, not just one pattern

The first three map to the enduring principles from the previous article:

"Make intent explicit" → Context Design + Precision
"Verify outputs" → Steering

The remaining two go further — asking whether the collaboration actually produces results (Output) and whether you're using AI's full range or stuck in a single pattern (Breadth).

Not "fewer prompts is better" — but "can you get it right with fewer exchanges?" Not "more commits" — but "are you actually achieving your goals?" That shift — from quantity to quality — is the whole point.

A note on methodology

These five axes weren't derived from a literature review or formal research. They emerged from iterating with AI itself — breaking down what "good collaboration" felt like across dozens of my own sessions, then pressure-testing the categories until they stopped overlapping. It's an opinionated framework, not a scientific instrument. I think that's okay for a self-reflection tool.

16 Style Types — A Bit of Fun That Stuck

After generating the 5-axis scores, I realized raw numbers are hard to talk about. "My Context Design is 76 and Breadth is 96" — not exactly cocktail-party material.

So I put together a personality-type system on a whim — classifying people by the shape of their radar chart. It turned out to be surprisingly intuitive, so it stuck.

The types are determined by which axes stand out, not by how high your scores are. It's about style, not rank. Here are a few:

The Sniper (Precision) — Minimum input, maximum output. One-shot instructions that just work.
The Architect (Context Design) — Master of setting the stage. The AI barely needs to ask questions.
The Explorer (Breadth) — Always finding new ways to use AI. First to try MCP, plugins, sub-agents.
The Surgeon (Precision + Steering) — Precision and finesse for tough problems.
The Virtuoso (Balanced) — Well-rounded across all axes.

There are 16 types in total (1 balanced + 5 primary + 10 hybrid). See the full list in the repo.

High scores across the board aren't the goal — every shape has meaning.

Honest Limitations

This is a self-reflection tool, not a performance metric. A couple of things to know:

Scores vary between runs. The qualitative assessment uses an LLM, so results aren't deterministic. That's a tradeoff of using AI-based evaluation — I leaned into it by emphasizing shape over absolute numbers.
Style is personal, not comparable. Common rubric, but not an identical scale. Your "72" and someone else's "72" don't mean the same thing. The radar chart shape is what matters.

There's also an inherent circularity worth naming: the tool uses an LLM to evaluate how well you work with an LLM. It may have blind spots — for example, favoring verbose sessions over terse-but-expert ones. I don't have a fix for that yet, but I think the transparency of the framework (all scoring logic is in the repo) helps.

How to Use It

It currently supports Claude Code session data. The five axes themselves are agent-agnostic by design — support for other agents is planned.

# 1. Clone & setup
git clone https://github.com/suruseas/ai-fluency.git
cd ai-fluency
npm install

# 2. Generate session analysis in Claude Code
claude> /insights

# 3. Generate your scorecard (English output)
npm run score           # → output/scores.json
npm run card            # → output/card-dark.svg, card-light.svg
npm run profile         # → output/profile.md

Or even simpler: if you're already in a Claude Code session, just type /ai-fluency — it handles everything in one shot.

This produces SVG cards (dark/light themes) and a Markdown ability sheet in output/. To embed the card in your GitHub README, see the instructions in the repo.

Wrapping Up

This started as my answer to a question I posed in my previous article: if lines of code and prompt counts are the wrong metrics, what should we look at?

My answer: Context Design, Precision, Steering, Output, Breadth — the quality of human-AI collaboration, not the volume.

It's not a perfect tool. But if it makes you stop and think, "Huh, so that's how I work with AI" — that's enough.

If you use Claude Code, it takes about 2 minutes. Drop your type in the comments — I'll compile the dev.to distribution in a follow-up post!

suruseas / ai-fluency

AI Fluency - Score your AI collaboration style across 5 axes

AI Fluency

GitHub プロフィールに貼れる「AI活用力」のスコアカード生成ツール。

AI エージェントとの協働スタイルを5軸でスコアリングし、SVGカードと能力シートを出力します。評価軸はエージェント共通の設計ですが、現時点では Claude Code のセッション分析データ（/insights で生成）に対応しています。

カード例

前提条件

現在の対応エージェント: Claude Code

Claude Code がインストール済みであること
Claude Code でのセッション履歴があること（分析対象データとして必要）

他の AI エージェントへの対応は今後追加予定です。

試してみる

1. リポジトリをクローンしてセットアップ

git clone https://github.com/suruseas/ai-fluency.git
cd ai-fluency
npm install

2. facets データを生成する

Claude Code で /insights を実行してください。セッション履歴が分析され、~/.claude/usage-data/facets/ に facets データ（JSON）が生成されます。

claude> /insights

Note: facets データがない状態では以降のステップは実行できません。

3. スコアカードを生成する

クローンしたディレクトリで Claude Code を起動し、/ai-fluency を実行します。

cd ai-fluency
claude

claude> /ai-fluency

直近3ヶ月分のデータを対象に、スコア算出からカード・能力シートの生成まですべて自動で行われます。

手動で実行する場合

# 定量スコアのみ算出（output/scores.json に出力）
npm run score

# SVG カードを生成（output/card-dark.svg, card-light.svg）
npm run card:ja     # 日本語版
npm run card        # 英語版（デフォルト）

# 能力シートを生成（output/profile.md）
npm run profile:ja  # 日本語版
npm run profile     # 英語版（デフォルト）

生成物はすべて output/ ディレクトリに出力されます。

注意: 生成物にはプロジェクト固有の情報は仕組み上含まれませんが、output/profile.md に機密情報が出力されていないことを公開前にご確認ください。

3. README に埋め込む

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/suruseas/ai-fluency/main/output/card-dark.svg">
  <img src="https://raw.githubusercontent.com/suruseas/ai-fluency/main/output/card-light.svg" alt="AI Fluency">
</picture>

スコアについて

スコアの一部（定性評価）は AI がセッション内容を読み取って判定しています。そのため以下の点にご注意ください。

再現性はありません — 同じデータでも実行ごとにスコアが多少変動します
…

View on GitHub

I Deleted 66% of My AI Coding Guide — Here's What Survived

yukihiro amadatsu — Wed, 18 Mar 2026 11:14:57 +0000

I started with 252 lines of AI coding principles. After four rounds of review, 86 lines survived. But first — a question.

Is your team measuring AI coding productivity by any of these?

Lines of code generated
Number of prompts per session
Response speed
Commit count
Number of AI tools adopted

If so, you might be optimizing for the wrong things. Lines-of-code targets reward bloat. Prompt-count targets punish thinking. Speed targets skip verification. When these metrics become goals, quality pays the price.

I wrote an 86-line document called The AI Coding Way that explains why — and what to measure instead. It tries to capture what stays true about human-AI coding collaboration, regardless of which tool or model you use.

What's in it

Three principles, in order of priority:

Keep things reversible (prerequisite) — Linters, tests, CI, version control. Safety enables boldness. You can't ask AI to refactor a module if you can't undo it.
Make your intent explicit (starting point) — Every context you give AI has three elements: purpose, constraints, and knowledge. Missing any one of them degrades output quality. Project-level intent (types, tests, naming conventions) compounds across every session.
Verify the output (non-negotiable) — The bottleneck has shifted from generation to verification. Code that was generated fast should be reviewed slow. The most expensive decision in AI coding: "it works, ship it."

One practice section covering the collaboration cycle (instruct → generate → verify → improve) and two habits: ask questions instead of giving instructions, and turn repeated instructions into project-level conventions.

One measurement section listing six metrics that are tempting to track but dangerous if used as goals: lines generated, prompt count, response speed, commit count, session count, tool count. These aren't useless — but optimizing for them alone leads you away from what matters. Measure density instead: acceptance rate, rework frequency, final code quality.

What's not in it

No tool names. No model names. No programming languages. No prompt templates. No opinions on whether AI is your boss, your colleague, your subordinate, or your tool — that's your call. The three principles apply regardless.

Why I wrote it

There are plenty of AI coding guides out there. Anthropic, OpenAI, and countless blog posts tell you how to write better prompts. But most of them have a shelf life of about six months — the next model update makes half the advice obsolete.

I wanted something different: a set of principles that hold true even as models get smarter, context windows get larger, and tools come and go.

So I set a rule: don't write anything that a better model would invalidate. "AI hallucinates" is a current fact, not a lasting principle. "AI output is probabilistic" is a lasting principle. "Context windows are small" will age poorly. "Humans are responsible for verifying output" won't.

How I wrote it

This document is itself a product of AI coding. AI agents debated the structure. AI generated the text. I made every decision on what to keep, what to cut, and how to frame it — exactly the cycle the document describes.

It started at 252 lines. Four AI agents reviewed it. One of them said: "A blog post would have been enough." That forced me to ask what actually survives if you strip everything away. For example, a full section called "AI's Amplification Effect" was cut as a standalone section — but its core insight ("AI amplifies both good and bad design") survived as two lines in the principles preamble. That's the kind of compression that happened across the board. The answer was 86 lines.

The full document

Here it is — the entire thing. 86 lines.

The AI Coding Way

Principles for AI Coding — v0.1, March 2026

If you write code with AI and want to get better at it, these principles are for you. Being a good engineer is the best AI strategy.

This document is meant to live in your project repository — not read once and forgotten, but referenced daily as shared understanding across your team. It will be revised based on real-world feedback.

Three Principles

AI output is probabilistic. The same instruction can produce different code. AI has knowledge gaps and states incorrect things with confidence. And AI amplifies — good intent produces good code at scale; sloppy instructions produce plausible but fragile code at scale. Given these properties, humans bear three responsibilities: intent, context, and verification.

These three principles are non-negotiable requirements for AI coding. The numbers indicate the order you should address them.

1. Keep things reversible (prerequisite)

The foundation for everything else. Without this, nothing is safe to try.

Prevention: Type checking, linters, test suites, CI. If AI-generated code doesn't meet the bar, it gets rejected automatically. The stronger your prevention, the bolder you can delegate.

Recovery: Version control, branching strategies, snapshots. The last line of defense when prevention fails.

Safety mechanisms are not constraints. They are the foundation that enables bold delegation.

2. Make your intent explicit (starting point)

Generating and verifying without clear intent is running without a map.

Context has three elements: purpose (what you want to achieve), constraints (what must not happen), and knowledge (background information needed for decisions). Without purpose, AI wanders. Without constraints, you get unwanted output. Without knowledge, AI guesses.

Intent operates at two levels. At the task level, you communicate purpose, constraints, and knowledge in your instructions. At the project level, type definitions, tests, naming conventions, and directory structure express intent — set these up once and they improve every session.

3. Verify the output (non-negotiable)

The bottleneck has shifted from generation to verification. Generation takes seconds. Verification takes human time. That's why the quality of your verification determines the quality of your outcomes.

The faster code was generated, the more carefully you should read it.

A common failure: AI generates 200 lines that appear to work. Tests pass. But half is unnecessary abstraction from trying to be too clean, and the rest silently swallows errors and breaks on edge cases. "It works, merge it" is the most expensive decision in AI coding.

Practice

AI coding follows this cycle:

Communicate — Pass purpose, constraints, and necessary knowledge to AI
Generate — AI produces code
Verify — Human judges the output
Improve — Revise instructions and context based on results

Skipping step 4 and jumping back to step 1 is the primary cause of spinning your wheels.

Ask questions, not just instructions. "Is there a problem with this design?" draws out more of AI's capability than "Write this function." When AI offers suggestions, dismissing them as "not what I asked for" is a missed opportunity.

If you're writing the same instructions every time, turn them into conventions. Put them in a rules file. Automate with hooks. What you systematize compounds across every future session.

What to Measure

The only measure of progress is working software.

The following metrics are tempting to track but dangerous when used as goals. They aren't useless as signals — but optimizing for them leads you away from what matters.

Lines generated. Measuring quantity incentivizes quantity.
Prompt count. Many exchanges signal low instruction quality, not productivity.
Response speed. Penalizes people who think before they instruct.
Commit count. Split commits and the number goes up. Measuring quantity invites inflation.
Session count. More isn't better. Context loss from session breaks can reduce efficiency.
Number of tools used. Using a tool and mastering a tool are different things.

The common problem: measuring quantity and speed incentivizes quantity and speed at the expense of quality.

Measure density instead. Acceptance rate. Rework frequency. Final code quality.

This document is a product of AI coding. AI agents debated, AI generated text, and a human made the decisions, verified the output, and revised it.

Whether you see AI as a subordinate, a collaborator, a supervisor, or a tool is up to you. The three principles apply regardless of what you expect from AI.

v0.1

This is v0.1, not a finished product. If you have feedback, I want to hear it. The only way this earns the right to be called a "guide" someday is through revision.

When AI Joins Your Team, Where Should You Focus Your Resources?

yukihiro amadatsu — Thu, 12 Mar 2026 12:42:44 +0000

I stopped thinking of AI as a tool.

Copilot, Cursor, Claude Code — once I started treating these not as "convenient assistants" but as "talented teammates," the way I develop software changed entirely.

And from that perspective, a simple question emerges.

If an exceptional coder and an exceptional reviewer were already on your team, where should the team focus its resources?

Don't Treat AI as Special — Just as an Exceptionally Talented Human

First, an important premise.

AI is not special. Treat it the same as a highly skilled human engineer.

AI can already write code, open pull requests, and leave review comments. The range of what it can do is expanding rapidly, and the justification for treating it differently "because it's AI" is fading. Think of it simply as having an exceptionally talented human engineer join the team.

With that premise in place, the opening question takes on meaning.

The Answer Is: Focus on Review

The conclusion first.

The team should focus on the review side — the process of questioning answers.

The reason is simple.

Generation (opening PRs) — let AI go all out.

Writing code is the process of "producing an answer given a set of requirements." This is where AI excels, and there's little reason for humans to run alongside it.

Review (questioning answers) — requires a perspective outside the generation context.

This is the core insight. As long as you remain inside the same context in which the code was generated, you cannot question it from the outside. Conversely, even the same model can function as a reviewer if it operates in a fresh session, disconnected from the generation context. Being outside the context is precisely what makes it possible to question the answer. Anthropic's Code Review, discussed later, is built on this same principle. Whether AI or human — "being outside the generation context" is the condition for effective review.

"Does this code work?" is not the question. "Was this the right implementation?" "Is this tradeoff really justified?" — raising these questions requires a perspective that differs from the one that produced the code. Focusing resources on review is what makes these questions possible.

Maybe Not a Coincidence — What Anthropic Is Doing

On March 9, 2026, Anthropic released Code Review for Claude Code.

The feature automatically dispatches multiple AI agents in parallel whenever a PR is opened, detects bugs, ranks them by severity, and feeds the results back into GitHub. Anthropic applies this system to nearly every PR internally, and the proportion of PRs receiving substantive review comments jumped from 16% to 54% as a result.

What's worth noting is the design philosophy. It has been reported that the tool focuses on logic errors, not style or naming conventions. Could this reflect a deliberate choice to leave style correction to the generation side?

This might be an embodiment of the idea: "rather than loading the generation side with detailed instructions, tighten the exit gate (review)."

Overloading CLAUDE.md Backfires

Meanwhile, research is emerging that questions the approach of controlling generation through detailed instructions.

A paper published on arXiv in February 2026, "Evaluating AGENTS.md" (ETH Zurich et al.), found that loading context files like CLAUDE.md or AGENTS.md with detailed instructions reduces task success rates and increases inference costs by more than 20%.

AI tries to follow instructions, but in doing so generates unnecessary exploration and testing that gets in the way of the actual task. The paper's conclusion is simple: "Unnecessary requirements make tasks harder. Context files should contain only minimal requirements."

Keeping instructions minimal — this direction may be empirically supported as well.

Skills Fall Into the Same Trap as CLAUDE.md

Agent Skills has been gaining attention recently. It's an open format for giving agents procedural knowledge via SKILL.md files, enabling capability expansion.

There are valid uses. Tasks like generating PPTX files or operating internal proprietary tools — adding capabilities that agents don't have out of the box. In that sense, it differs from CLAUDE.md.

But misused, it falls into exactly the same trap.

Consider writing a rule like "always include the time, not just the date, in Rails migration filenames" as a Skill. This is just injecting a corrective instruction as a workaround for unstable output — structurally no different from writing it in CLAUDE.md.

A practical rule of thumb: if it can be replaced by a linter or automation tool, it shouldn't be a Skill.

Skill type	Verdict
Cannot be replaced by linters etc. (capability expansion)	Valid
Can be replaced by linters etc. (rule correction)	Same trap as CLAUDE.md

When you find yourself wanting to create a Skill to enforce a rule, first ask whether a linter or automation tool could handle it instead. If it can, it belongs at the exit gate — not injected into the generation side.

Scale Benefits Belong on the Review Side

AI scales. That's true for generation too — but I believe scale truly pays off on the review side.

On the generation side, there's a "lottery approach": keep asking AI to regenerate until you get a good result. More attempts eventually yield better output.

That said, I personally accept about 90% of AI output as-is. I think it's because I use AI as a collaborative partner rather than giving it detailed instructions. If generation quality is already high enough, there's no need to rely on the lottery approach. If you're going to invest scale somewhere, review is the more rational choice.

What happens when you invest scale in review? Multiple AIs independently question the same PR. Each raises questions from different angles, catching what others miss. Anyone who has worked in code review knows the feeling of "I want as many eyes on this as possible" — review works the same way. The more reviewers, the lower the probability of something slipping through.

Anthropic itself has adopted a design for Code Review that runs multiple agents in parallel, then cross-checks to filter out false positives. Could this also be seen as an embodiment of the idea that scale belongs on the review side?

The lottery approach in generation just accumulates cost. Scale in review has intrinsic value: it reduces what gets missed.

Human Eyes Still Have Unique Value

Does this mean humans are unnecessary if AI handles review? I don't think so.

Business judgment, implicit team context, "this is technically correct but is it acceptable for our organization?" — these are areas where humans currently have an edge over AI. That's why there's still good reason for humans to actively invest time in review.

Scale AI in review, and have humans actively invest in review too. Increasing both kinds of "eyes" raises the quality of the team's answers.

Summary

Process	Who does it	What scale means
Generation (opening PRs)	Let AI go all out	More output, but no gain in quality
Review (questioning answers)	Invest both AI and humans	Quality improves

When AI joins the team, the team's job is not to "beat AI at generation." It's to question the answers AI produces — together.

Closing

Behind Anthropic's release of Code Review lies a real problem: AI is generating so much code that review has become a bottleneck. Code output per engineer at Anthropic has grown 200% over the past year.

This trend won't stop. Generation will keep increasing, and the importance of review will only grow.

If you truly trust AI as a teammate, let them go all out producing answers. And as a team, concentrate your resources on questioning those answers.

Concretely: adopting tools like Code Review, enforcing style conventions with linters and automation, and making sure humans have time for review — these three are a good place to start.

That's my conclusion for now.

References

DEV Community: yukihiro amadatsu

I ran 156 real-world docker compose projects on Apple's container. The failures fell into patterns a machine can fix

Setup

The raw numbers first

Counting the failures

Group 1: nothing to do with Apple's container

Group 2: failures that are Apple-container-specific

Pattern 1: named volumes are mount points

Pattern 2: bind mounts can't be chowned

If the fix is deterministic, a machine can apply it

So how many did it save?

The timeout misclassified one project

What I didn't do / can't claim

What counting taught me

Apple's container makes no sense as a Docker replacement — until you see it as a box for AI agents

A design that keeps losing benchmarks

Exhibit 1: the parts list is suspicious

Exhibit 2: this is how Apple has always done safety

Exhibit 3: you can already build the box — with a compose file

The weak side: egress

"Why not just use Docker Sandboxes?"

Exhibit 4: the same principle, invented three times

Verdict

Honest caveats

Summary

Your Claude Code MCP servers are quietly costing you gigabytes of RAM

The .mcp.json you probably have

MCP servers are the shape Apple container is good at

Migrating (about a minute)

Where the raw command stops being enough

1. A server that needs a token

2. Several servers

3. An HTTP-transport server

The trap I actually hit

Honest caveats

Summary

Apple's container hit 1.0. Should it be your dev environment yet? I measured.

Introduction

Part 1 — Compatibility: better than I expected

Setup

The results

The one-line fixes (and what they reveal)

Postgres refuses its data volume (3 samples)

amd64-only images (1 sample)

The ones that were broken before I arrived (5 samples)

Can't run by design (3 samples)

The rest

Gotchas beyond this sample set

Part 2 — Performance: this is where it's behind today

The verdict: when to pick it (and when not to, yet)

So if not docker compose, what is it for?

Try it yourself — it's safe next to Docker

Closing notes

I ran 29 real docker-compose projects on Apple's container runtime. Here's what broke

Setup

The results

The one-line fixes (and what they reveal)

Postgres refuses its data volume (3 samples)

amd64-only images (1 sample)

The ones that were broken before I arrived (5 samples)

Can't run by design (3 samples)

The rest

Gotchas beyond this sample set

Try it on your own compose file

I ran 29 real docker-compose projects on Apple's container runtime. Here's what broke

Setup

The results

The one-line fixes (and what they reveal)

Postgres refuses its data volume (3 samples)

amd64-only images (1 sample)

The ones that were broken before I arrived (5 samples)

Can't run by design (3 samples)

The rest

Gotchas beyond this sample set

Try it on your own compose file

Run your docker-compose.yml on Apple's container runtime

Install

Just try it on a project you already have

opossum up

opossum ps

The `.mcp.json` you probably have

`opossum up`

`opossum ps`

`opossum logs` and `opossum stats`

`opossum down`