opencode-skills-collection 3.1.23 → 4.0.1

package/bundled-skills/apple-container/references/configuration.md

@@ -0,0 +1,499 @@
+# Configuration & administration
+
+Admin guide for Apple's `container` CLI runtime (Apple silicon macOS). This is **not Docker** —
+the CLI is Docker-like but the runtime is a per-container lightweight VM. For exhaustive
+flags/subcommands see `commands.md`; this file covers the operator surface only.
+
+The runtime is a set of launchd-managed services (`container-apiserver` + machine API server +
+background helpers). Almost everything below drives those services. Every command accepts
+`--debug` (env `CONTAINER_DEBUG`). Most `list`/`status` commands accept `--format` — commonly
+`json`, `table`, `yaml`, and `toml` (the exact value set and default vary by command, e.g. `table`
+for `container list` but `toml` for `system property list`; check `<command> --help`).
+
+---
+
+## 1. System service: start / stop / status / logs
+
+The `container` services must be running before any container/image/build command works.
+
+```bash
+container system start        # register services in launchd, launch apiserver + machine API
+container system status       # health-check; prints running state + data/install roots
+container system stop         # stop all services and deregister from launchd
+container system logs         # recent service logs (default last 5m)
+container system logs -f      # live tail
+container system logs --last 1h
+```
+
+`system start` behavior worth knowing:
+- Launches `container-apiserver` via launchd, then **pings it** and fails if unresponsive
+  (bump `--timeout <seconds>` on slow machines).
+- On first run it **installs the base filesystem (`vminit`) image** and prompts to install the
+  **default kernel** unless you pass `--enable-kernel-install` / `--disable-kernel-install`.
+- Loads `config.toml` (see §2) once, at startup. **Restart after any config/property change:**
+  `container system stop && container system start`.
+
+| `system start` flag | Purpose | Default |
+|---------------------|---------|---------|
+| `-a, --app-root <path>` | Application data root | `~/Library/Application Support/com.apple.container/` |
+| `--install-root <path>` | Executables/plugins root | `/usr/local/` |
+| `--log-root <path>` | Log dir; unset → macOS unified log | unset |
+| `--enable-kernel-install` / `--disable-kernel-install` | Install default kernel or not (mutually exclusive) | prompt |
+| `--timeout <seconds>` | Wait for apiserver readiness | XPC default |
+
+`system stop` takes `-p, --prefix <prefix>` (launchd prefix, default `com.apple.container.`);
+`system status` takes the same `--prefix` plus `--format`.
+
+`system df` shows reclaimable disk usage for images/containers/volumes:
+```bash
+container system df --format json
+```
+
+**Data locations** (reported by `system status`):
+
+| Location | Default path |
+|----------|--------------|
+| App data root | `~/Library/Application Support/com.apple.container/` |
+| Install root | `/usr/local/` |
+| User config | `~/.config/container/config.toml` |
+| Package config | `<installRoot>/etc/container/config.toml` (e.g. `/usr/local/etc/...`) |
+
+Data root holds `apiserver/`, `builder/`, `containers/`, `content/`, `kernels/`, `networks/`,
+`volumes/`, `snapshots/`, `plugin-state/`, `user-plugins/`, and `state.json`.
+
+---
+
+## 2. System properties / config.toml
+
+One `ContainerSystemConfig` drives the runtime. **Configure it by editing `config.toml`**;
+`container system property list` is a read-only view of the effective (merged) values.
+
+- **`config.toml`** section tables (`[build]`, `[container]`, …) are loaded at service startup,
+  first-match-wins across `~/.config/container/config.toml` then
+  `<installRoot>/etc/container/config.toml`. Missing keys fall back to hardcoded defaults.
+- **Flat property IDs** (e.g. `build.rosetta`, `dns.domain`) are how the same values are named
+  and reported. `container system property` has only the `list` subcommand — there is **no**
+  per-key `get`, `set`, or `clear`. To change a value edit `config.toml`; to revert one, remove
+  its key.
+
+Property ID ⇄ TOML mapping is direct: `build.rosetta` ⇄ `[build] rosetta`, etc. (exceptions:
+the builder/vminit image IDs — see table).
+
+```bash
+# View effective values (read-only)
+container system property list                 # all IDs, types, current values (default: toml)
+container system property list --format json
+```
+
+```toml
+# Change values by editing ~/.config/container/config.toml, then restart services
+[container]
+cpus = 8
+[registry]
+domain = "ghcr.io"
+```
+```bash
+container system stop && container system start   # apply; remove a key to revert it
+```
+
+**Every configurable key:**
+
+| Property ID | TOML | Type | Default | Meaning |
+|-------------|------|------|---------|---------|
+| `build.rosetta` | `[build] rosetta` | Bool | `true` | Build amd64 images on arm64 via Rosetta (else QEMU) |
+| `build.cpus` | `[build] cpus` | Int | `2` | Builder VM CPU count |
+| `build.memory` | `[build] memory` | MemorySize | `"2048mb"` | Builder VM RAM |
+| `image.builder` | `[build] image` | String | `ghcr.io/apple/container-builder-shim/builder:<ver>` | Builder (BuildKit) image reference |
+| `container.cpus` | `[container] cpus` | Int | `4` | Default CPUs per container (when `run`/`create` omit `--cpus`) |
+| `container.memory` | `[container] memory` | MemorySize | `"1g"` | Default RAM per container |
+| `dns.domain` | `[dns] domain` | String? | unset | Local domain appended to unqualified container names (§4) |
+| `registry.domain` | `[registry] domain` | String | `"docker.io"` | Default registry for bare image refs (§5) |
+| `kernel.url` | `[kernel] url` | URL | kata-static release URL | Kernel file or archive to install (§3) |
+| `kernel.binaryPath` | `[kernel] binaryPath` | String | `opt/kata/share/kata-containers/vmlinux-<ver>` | Archive-member path of the kernel |
+| `network.subnet` | `[network] subnet` | CIDRv4? | unset | Default IPv4 subnet for networks; auto-allocates when unset (§7) |
+| — | `[network] subnetv6` | CIDRv6? | unset | Default IPv6 prefix for networks; auto-allocates when unset (§7) |
+| `image.init` | `[vminit] image` | String | `ghcr.io/apple/containerization/vminit:<ver>` | `vminitd` image booting container VMs |
+| — | `[plugin.<id>]` | — | — | Plugin-scoped config; each plugin reads only its own section |
+
+> Exact defaults (kernel version, image tags) drift per release. Confirm with
+> `container system property list`; do not assume a specific version.
+
+**MemorySize** = quoted string, integer + binary unit (`b/kb/mb/gb/tb/pb`, powers of 1024, case-insensitive);
+bare integer = bytes. `"2g"` re-emits as `"2gb"`. **CIDR** = quoted, e.g. `"192.168.100.0/24"`.
+
+Minimal `config.toml` example:
+```toml
+[container]
+cpus = 8
+memory = "4g"
+[dns]
+domain = "test"
+```
+
+The full per-section `config.toml` schema (keys, types, defaults, meaning), the flat property
+list as emitted by the CLI, type-format details, and data locations are in the
+[appendix](#appendix-configtoml-schema--data-locations).
+
+---
+
+## 3. Default kernel
+
+The default guest kernel is the Linux kernel every container VM boots. Managed via
+`container system kernel set` (writes the default) plus the `kernel.url` / `kernel.binaryPath`
+properties (the download source `--recommended` uses).
+
+```bash
+container system kernel set --recommended        # download + install Apple's recommended kernel
+container system kernel set --binary ./vmlinux --force            # install a local binary, overwrite
+container system kernel set --tar https://ex.com/kata-static.tar.xz \
+  --binary opt/kata/share/kata-containers/vmlinux-6.12.28-153 --arch arm64
+```
+
+| Flag | Purpose | Default |
+|------|---------|---------|
+| `--recommended` | Download+install recommended kernel. **Overrides `--arch`/`--binary`/`--tar`** | — |
+| `--arch <amd64\|arm64>` | Kernel architecture | `arm64` |
+| `--binary <path>` | Kernel file, or archive-member name when used with `--tar` | — |
+| `--tar <path\|url>` | Tar archive (local or remote) containing the kernel | — |
+| `--force` | Overwrite an existing kernel of the same name | — |
+
+- Persist a custom source by editing `config.toml`:
+  ```toml
+  [kernel]
+  url = "<url>"
+  binaryPath = "<member>"
+  ```
+- Kernel install is also toggled at startup via `system start --enable/--disable-kernel-install`.
+- Per-machine kernel override is separate — see §7 (`machine set kernel=<path>`).
+
+---
+
+## 4. DNS / local domain resolution
+
+Register a **local DNS domain** so unqualified container names resolve host-side (e.g.
+`my-web` → `my-web.test`). Creating/deleting a domain **modifies the host resolver and
+requires admin** (`sudo`); it restarts `mDNSResponder`.
+
+```bash
+sudo container system dns create test               # register domain "test"
+sudo container system dns create test --localhost 127.0.0.1   # redirect an IPv4 to localhost
+container system dns list                            # list domains (no sudo)
+sudo container system dns delete test                # alias: rm
+```
+```toml
+# Activate "test" as the default domain in ~/.config/container/config.toml
+[dns]
+domain = "test"
+```
+```bash
+container system stop && container system start
+```
+
+- `--localhost` must be a valid **IPv4** address; it installs a pf redirect rule to `127.0.0.1`.
+- Registering a domain is not enough — set `[dns] domain` in `config.toml` to activate it for
+  unqualified names.
+- If domain deactivation misbehaves: `sudo killall -HUP mDNSResponder`.
+
+---
+
+## 5. Default registry & authentication
+
+Bare image refs resolve against the default registry (`registry.domain`, default `docker.io` →
+`alpine` becomes `docker.io/library/alpine`).
+
+```toml
+# Change the default registry in ~/.config/container/config.toml (restart to apply);
+# remove the key to revert to docker.io
+[registry]
+domain = "ghcr.io"
+```
+
+**Auth** (`container registry`, alias `r`) — credentials are stored in the macOS keychain:
+
+```bash
+container registry login registry.example.com            # prompts user + password
+container registry login -u alice ghcr.io                # prompt password only
+echo "$TOKEN" | container registry login -u alice --password-stdin ghcr.io   # non-interactive
+container registry list                                  # HOSTNAME/USERNAME/MODIFIED/CREATED (1.0.0+)
+container registry logout ghcr.io
+```
+
+| Command | Key flags | Notes |
+|---------|-----------|-------|
+| `login <server>` | `-u/--username`, `--password-stdin`, `--scheme <http\|https\|auto>` | `--password-stdin` **requires** `--username`. On success pings the registry then saves to keychain |
+| `logout <registry>` | — | Deletes keychain creds for the resolved host |
+| `list` (`ls`) | `--format`, `-q/--quiet` | `-q` prints hostnames only |
+
+**Insecure / HTTP registries** — `--scheme` (default `auto`):
+- `auto` → `http` for internal/private hosts (`localhost`, the internal DNS domain, and RFC-1918
+  ranges `10/8`, `127/8`, `192.168/16`, `172.16/12`); `https` for everything else.
+- Force plaintext against a local registry: `container registry login --scheme http localhost:5000`.
+- `--scheme` also applies to image `pull`/`push` and `machine create` (same enum).
+
+> `registry list` only lists saved logins. There is no `default-registry get/set` subcommand —
+> the default registry lives in the `registry.domain` property (above).
+
+---
+
+## 6. BuildKit builder VM
+
+`container build` runs inside a utility container named **`buildkit`** (a lightweight VM). It
+auto-starts on first build; manage it explicitly with `container builder` when you need more
+resources or a clean slate.
+
+```bash
+container builder start --cpus 8 --memory 32g    # start with more resources
+container builder status                          # ID/IMAGE/STATE/IP/CPUS/MEMORY
+container builder stop
+container builder delete                          # alias: rm  (add --force if running)
+```
+
+To resize a running builder, recreate it:
+```bash
+container builder stop && container builder delete && container builder start --cpus 8 --memory 32g
+```
+
+| Command | Flags | Notes |
+|---------|-------|-------|
+| `start` | `-c/--cpus <n>`, `-m/--memory <size>` (K/M/G/T/P suffix) | Falls back to `build.cpus`/`build.memory` (defaults 2 CPUs / 2048 MiB). Reuses an existing matching builder; recreates if image/cpu/mem/env/DNS changed |
+| `status` | `--format`, `-q/--quiet` | Prints `builder is not running` when absent |
+| `stop` | — | No-op warning if not running |
+| `delete` (`rm`) | `-f/--force` | Errors unless stopped; `--force` stops then deletes |
+
+- Image comes from `image.builder` / `[build] image`; Rosetta-vs-QEMU for amd64 builds is
+  `build.rosetta`.
+- Persistent builder defaults (not just this session) go in `[build] cpus` / `[build] memory`
+  in `config.toml`.
+
+---
+
+## 7. Machines, custom networks, volumes
+
+### Machines (`container machine`, alias `m`)
+
+> **⚠️ Requires 1.0.0+ — the `container machine` group was added in 1.0.0 (not in 0.7.1).**
+
+A **container machine** is a persistent, bootable Linux **environment** (not a one-shot
+container) — it runs the image's init system, auto-mounts your macOS `$HOME` and username, and
+persists across restarts. Ideal for "edit on Mac, build inside Linux" and running long-lived
+services. Distinct from the transient per-container VMs that back `container run`.
+
+```bash
+container machine create alpine:3.22 --name dev --set-default
+container machine run                 # interactive shell in the default machine (matches host user)
+container machine run -n dev uname
+container machine run -n dev -- cat /proc/cpuinfo    # everything after -- passed through verbatim
+container machine list                # ls: NAME/CREATED/IP/CPUS/MEMORY/DISK/STATE/DEFAULT(*)
+container machine inspect dev         # JSON detail
+container machine set -n dev cpus=4 memory=8G home-mount=ro    # takes effect after stop/start
+container machine set-default dev
+container machine stop dev
+container machine delete dev          # rm: also deletes persistent storage
+container machine logs -f -n 100 dev  # --boot for boot log
+```
+
+| Subcommand | Key flags / settable keys | Notes |
+|------------|---------------------------|-------|
+| `create <image>` | `-n/--name`, `--set-default`, `--no-boot`, `--cpus`, `--memory`, `--home-mount <ro\|rw\|none>`, `--virtualization`, `--kernel <path>` | Memory default = half host RAM; home-mount default `rw`. Name defaults to `<image>-<tag>` |
+| `set [-n]` | `cpus=`, `memory=`, `home-mount=`, `virtualization=<bool>`, `kernel=<path>` (empty `kernel=` resets to default) | `key=value`; last dupe wins; unknown key errors. Changes apply after stop/start |
+| `run` | `-d/--detach`, `--root`, `-e/--env`, `-i`, `-t`, `-u/--user`, `-w/--workdir`, `--ulimit` | Boots machine if stopped; forwards `SSH_AUTH_SOCK` |
+| `logs` | `--boot`, `-f/--follow`, `-n <lines>` | `-n` is short-only |
+| `list`/`inspect`/`stop`/`delete`(`rm`)/`set-default` | ID optional (uses default) except `set-default`/`delete` | — |
+
+**Nested virtualization / custom kernel** (per-machine): requires Apple Silicon **M3+** on
+**macOS 15+** and a kernel with `CONFIG_KVM=y` (the default kernel does not qualify).
+```bash
+container machine create --virtualization --kernel /path/to/vmlinux-kvm -n kvm-dev alpine:latest
+container machine run -n kvm-dev -- ls -l /dev/kvm     # verify /dev/kvm exposed
+```
+Any Linux image with `/sbin/init` works. Override first-boot user provisioning by adding an
+executable `/etc/machine/create-user.sh` (runs once as root; env `CONTAINER_{UID,GID,USER,HOME,MACHINE_ID}`).
+
+### Custom networks (`container network`, alias `n`) — **macOS 26+**
+
+`system start` always creates a builtin vmnet network `default`. On **macOS 26+** you can create
+additional **isolated** networks (no cross-network connectivity). Builtin networks cannot be deleted.
+
+```bash
+container network create foo                                   # prints network ID
+container network create foo --subnet 192.168.100.0/24 --subnet-v6 fd00:1234::/64
+container network list                                         # ls: NETWORK/SUBNET
+container network inspect foo                                   # pretty JSON
+container run -d --name web --network foo web-test             # attach a container
+container network delete foo                                   # rm; add --all for all non-builtin
+container network prune                                        # remove networks with no attached containers
+```
+
+| Flag (`create`) | Purpose | Default |
+|-----------------|---------|---------|
+| `--subnet <cidr4>` / `--subnet-v6 <cidr6>` | Custom subnets (validated non-overlapping) | auto-allocate / `network.subnet(v6)` |
+| `--internal` | Host-only network (no NAT) | NAT |
+| `--label k=v` / `--option k=v` | Metadata / plugin option (repeatable) | — |
+| `--plugin <name>` | Network plugin | `container-network-vmnet` |
+
+`delete --all` skips builtin networks; deleting a network fails if any IP is still in use.
+Persistent default subnets → `network.subnet` / `[network] subnetv6`. Their effect is
+version-dependent: on **macOS 15** they set the subnet of the single builtin `default` network;
+on **macOS 26+** they additionally seed the default subnet for custom networks created without an
+explicit `--subnet`/`--subnet-v6`. In both cases, if left unset the system auto-allocates a
+non-overlapping subnet.
+
+### Volumes (`container volume`, alias `v`)
+
+A **volume** is host-backed storage you mount into containers to persist/share data across runs
+(`container run --volume <name>:/path` or a host `path:path`). Driver is always `local`.
+
+```bash
+container volume create mydata -s 10G                         # prints volume name (-s takes K/M/G/T/P)
+container volume create mydata --label env=dev --opt key=val
+container volume list                                          # ls: NAME/TYPE/DRIVER/OPTIONS
+container volume inspect mydata                                # pretty JSON
+container volume delete mydata                                 # rm; --all for all volumes
+container volume prune                                         # remove volumes with no container refs; reports reclaimed space
+```
+
+| Flag (`create`) | Purpose |
+|-----------------|---------|
+| `-s <size>` | Size in bytes, K/M/G/T/P suffix (stored as driver opt `size`) |
+| `--label k=v` | Metadata (repeatable) |
+| `--opt k=v` | Driver-specific option (repeatable) |
+
+`delete`/`network delete` require either names **or** `--all` (not both); a missing named
+resource errors, while `--all` tolerates an empty set.
+
+---
+
+## Appendix: `config.toml` schema & data locations
+
+One underlying `ContainerSystemConfig` is configured by editing a **`config.toml`** file with
+`[section]` tables loaded once at service startup. The same values are also named as flat
+**property IDs** (`build.rosetta`, `dns.domain`, …) — view them read-only with
+`container system property list` (its only subcommand; there is no `get`/`set`/`clear`). Property
+IDs map onto TOML sections directly (`build.rosetta` ⇄ `[build] rosetta`), with two naming
+exceptions: the builder image is `image.builder` ⇄ `[build] image`, and the vminitd image is
+`image.init` ⇄ `[vminit] image`. For the CLI commands themselves see `commands.md`.
+
+### Sources & precedence
+
+TOML is loaded **first-match-wins**, then any key absent from both files falls back to a
+hardcoded default:
+
+1. User file — `~/.config/container/config.toml`
+2. Package file (optional) — `<installRoot>/etc/container/config.toml`
+   (e.g. `/usr/local/etc/container/config.toml`)
+
+The file is read **once at startup**; restart after edits
+(`container system stop && container system start`).
+
+### Top-level sections
+
+```toml
+[build]        # builder VM resources and image
+[container]    # default per-container resources
+[dns]          # default DNS domain for host DNS resolution
+[kernel]       # guest kernel binary path and download URL
+[network]      # default subnets for networks
+[registry]     # default registry domain
+[vminit]       # default vminitd image
+[plugin.<id>]  # zero or more plugin-scoped sections
+```
+
+All sections are optional; an omitted section falls back to its defaults wholesale. (The Swift
+source also defines an internal `[machine]` section, not part of the documented user schema.)
+
+### `[build]` — builder VM (runs `container build`)
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `rosetta` | `build.rosetta` | Bool | `true` | Build amd64 images on arm64 using Rosetta translation, instead of QEMU. |
+| `cpus` | `build.cpus` | Int | `2` | CPU count for the builder VM. |
+| `memory` | `build.memory` | MemorySize | `"2048mb"` | RAM allocation for the builder VM. |
+| `image` | `image.builder` | String | `ghcr.io/apple/container-builder-shim/builder:<tag>` | Reference for the builder image; `<tag>` tracks the bundled `container-builder-shim` version. (Property ID is `image.builder`, not `build.image` — see the naming exception above.) |
+
+### `[container]` — default per-container resources
+
+Applied when `container run` / `container create` runs without `--cpus` / `--memory`.
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `cpus` | `container.cpus` | Int | `4` | Default CPU count per container. |
+| `memory` | `container.memory` | MemorySize | `"1g"` | Default RAM per container. |
+
+### `[dns]` — local DNS domain
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `domain` | `dns.domain` | String? | unset | Local DNS domain appended to unqualified container hostnames. `"test"` makes `my-web` resolvable as `my-web.test`. Unset → no domain appended. See §4 for the register-then-activate workflow. |
+
+### `[kernel]` — default guest kernel
+
+Defaults change per release as kernels are bumped; confirm with
+`container system property list`.
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `binaryPath` | `kernel.binaryPath` | String | `opt/kata/share/kata-containers/vmlinux-<ver>` | Archive-member pathname of the kernel, when the URL points at an archive. |
+| `url` | `kernel.url` | URL | kata-static release `.tar.xz`/`.tar.zst` | URL of the kernel file to install, or of an archive containing it. |
+
+### `[network]` — default subnets
+
+Used when creating networks without explicit `--subnet` / `--subnet-v6`. See §7 for the
+macOS 15 vs macOS 26+ behavior.
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `subnet` | `network.subnet` | CIDRv4? | unset | IPv4 CIDR, e.g. `"192.168.100.0/24"`. Unset → system auto-allocates a non-overlapping subnet. |
+| `subnetv6` | — | CIDRv6? | unset | IPv6 CIDR, e.g. `"fd00:abcd::/64"`. Unset → system auto-allocates. |
+
+### `[registry]` — default registry
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `domain` | `registry.domain` | String | `"docker.io"` | Default registry for image references that omit a registry host (`alpine` → `docker.io/library/alpine`). See §5. |
+
+### `[vminit]` — default vminitd image
+
+| Key | Property ID | Type | Default | Description |
+|-----|-------------|------|---------|-------------|
+| `image` | `image.init` | String | `ghcr.io/apple/containerization/vminit:<tag>` | Reference for the `vminitd` image used to boot container VMs; `<tag>` tracks the bundled `containerization` version. |
+
+### `[plugin.<id>]` — plugin-scoped config
+
+Plugins ship their own schemas under `[plugin.<id>]` (`<id>` = plugin identifier). Each plugin
+defines and reads only its own section; values cannot leak across plugins. Consult the specific
+plugin's documentation for its keys.
+
+### Type formats
+
+**MemorySize** — a quoted string: numeric prefix + binary unit suffix (case-insensitive). All
+units are **binary** (powers of 1024) even when written `kb`/`mb`/`gb`. A bare integer (`"2048"`)
+parses as bytes. Encoded form uses lowercase `b`/`kb`/`mb`/`gb`/`tb`/`pb` (so `"2g"` re-emits as
+`"2gb"`).
+
+| Suffix family | Unit | Examples |
+|---------------|------|----------|
+| `b` | bytes | `"1024b"` |
+| `k`, `kb`, `kib` | kibibytes (1024 B) | `"512k"`, `"512kb"` |
+| `m`, `mb`, `mib` | mebibytes | `"2048mb"` |
+| `g`, `gb`, `gib` | gibibytes | `"4g"`, `"4gb"` |
+| `t`, `tb`, `tib` | tebibytes | `"1t"` |
+| `p`, `pb`, `pib` | pebibytes | `"1p"` |
+
+**CIDRv4 / CIDRv6** — quoted strings, e.g. `"192.168.100.0/24"` and `"fd00:abcd::/64"`. Invalid
+CIDR strings are rejected at decode time.
+
+### Data locations
+
+Reported by `container system status`:
+
+| Location | Path (default) | Overridable with |
+|----------|----------------|------------------|
+| Application data root | `~/Library/Application Support/com.apple.container/` | `container system start --app-root <path>` |
+| Application install root | `/usr/local/` | `container system start --install-root <path>` |
+| Log root | macOS unified log facility (if unset) | `container system start --log-root <path>` |
+| User config file | `~/.config/container/config.toml` | — |
+| Package config file | `<installRoot>/etc/container/config.toml` (e.g. `/usr/local/etc/container/config.toml`) | — |
+
+The data root contains subdirectories such as `apiserver/`, `builder/`, `containers/`,
+`content/`, `kernels/`, `networks/`, `plugin-state/`, `snapshots/`, `user-plugins/`, `volumes/`,
+and a top-level `state.json`.