apple-container-skill

Apple Container スキル

Apple の container CLI を、macOS ネイティブの Linux コンテナランタイムとして操作します。このスキルは、コマンドの構文を示すだけでなく、エージェントが適切な選択をできるよう導くものです。

最初に行うこと

実際の作業を始める前に、ホストとランタイムが使用可能か確認します。

sw_vers
uname -m
command -v container
container --version
container system status
container system version

• サポート対象のワークフローには、Apple シリコン（arm64）と macOS 26 以降が必要です。Apple はそれより古い macOS リリースをサポートしていません。macOS 15 の回避策を、サポート対象の操作として提示しないでください。
• CLI とサービスのバージョンを記録し、現在の署名済みリリースと照合して、実際の作業を始める前に両者が一致していることを確認します。2026 年 10 月現在、1.5.0 は信頼できないイメージ、イメージアーカイブ、レジストリ、コンテナ識別子、または実験的な Kubernetes の使用におけるセキュリティの基準バージョンです。1.3.1 と 1.4.1 では、パストラバーサル、ホストファイルへのアクセス、認証情報の処理、および関連する OCI の不具合が修正され、1.5.0 では、ゲストから提供された kubeconfig の値をホストの kubeconfig に統合する前にサニタイズします。アップストリームですでに修正済みの不具合に対して回避策を考案する前に、アップグレードしてください。
• CLI が見つからない場合は、GitHub リリースページから Apple の署名済みインストーラーを使うことを推奨します。Homebrew でも動作しますが、Homebrew でインストールした後に container system start がプラグイン不足で失敗する場合は、フォーミュラをアップグレードまたは再インストールしてください。
• ステータスでサービスが停止中と表示される場合は、container system start でサービスを起動します。初回起動時に、推奨 Linux カーネルのインストールを求められることがあります。
• インストール済みの container <command> --help を、利用可能なコマンドの正式な情報源として扱います。リリースの概要や、生成されたコマンドリファレンスでさえ、出荷済みパーサーの内容に追いついていないことがあります。Docker のサブコマンドやフラグを推測しないでください。
• アプリケーションコードを疑う前に、スモークテストを実行します。

container run --rm docker.io/library/alpine:latest sh -lc 'uname -a; nslookup github.com'

環境が不明、または不安定な場合は、同梱の診断を実行します。

bash skills/apple-container-skill/scripts/diagnose.sh

適切なランタイム構成を選ぶ

• 破棄可能なアプリコンテナ、単発の Linux コマンド、プロジェクトの開発シェル、イメージのスモークテスト、状態をバインドマウントまたは名前付きボリュームに保存するサービスには、container run を使います。
• ディストリビューションの繰り返しテスト、システムサービス、VS Code Remote SSH、永続的なルートファイルシステム、または「macOS で編集し、Linux 内でビルドする」作業には、長期間使う Linux ワークスペースとして container machine を使います。
• 実験的な container k8s は、破棄可能なローカルの単一ノード Kubernetes クラスターに限って使います。これを本番用またはマルチノードの Kubernetes ランタイムとして提示しないでください。また、作成時には kubeconfig のエントリが書き込まれるか更新され、削除時にはそのクラスターのエントリが削除されることを警告してください。1.5.0 に container k8s start はありません。停止したクラスターを再起動するには削除してから再作成し、古い例からコピーした start コマンドをスクリプトに含めないでください。
• マシンを単なる「永続コンテナ」と説明しないでください。マシンは、コンテナ、別個の永続ルートディスク、ホストとの統合を組み合わせた便利なラッパーです。ホストユーザーをマッピングし、SSH エージェントのサポートを転送します。また、macOS のホームディレクトリを /Users/<user> にマウントする一方で、Linux ユーザーの $HOME は /home/<user> になります。
• 現行の Container Machine イメージには /sbin/init が必要です。Apple Container 1.3 ではマシンのパス制限が緩和され、現在の Apple のガイダンスでは alpine:latest をそのまま使っています。現行リリースでは、カスタムイメージを派生させる前に、/sbin/init を含む指定イメージを試してください。init がない場合や、ワークフローで管理対象のシステムサービスが必要な場合は、OpenRC または systemd に対応したイメージをビルドします。
• スクリプトからマシンコマンドを実行する場合は、オプション終端子を使うことを推奨します。例：container machine run -n dev -- whoami または container machine run -n dev -- /bin/sh -c 'whoami; pwd; echo "$HOME"'。ヒアドキュメントを使うスクリプトや非対話型スクリプトでは、-i を避けてください。標準入力からスクリプトの残りの部分まで読み込んでしまうことがあります。

マシンイメージの選択

ユーザーがディストリビューションのイメージを指定した場合は、ディストリビューションの選択を維持しつつ、実行環境の種類を適切に選択します。

• 単発のコマンドやアプリケーションコンテナでは、指定されたイメージを container run で直接使用します。
• container machine では、指定されたイメージに /sbin/init が含まれていることを確認します。Apple Container 1.3 以降では、その要件を満たす標準イメージを直接使用します。Apple の現在のクイックスタートでは alpine:latest が使われています。
• /sbin/init がない場合、またはユーザーが systemd 管理のサービスを必要としている場合は、その要件を説明し、ディストリビューションを黙って切り替えるのではなく、指定されたベースイメージからマシンイメージを作成します。
• Alpine マシンでは、openrc と openrc-init の両方をインストールし、関連するユーザーおよびネットワークツールを追加して、CMD ["/sbin/openrc-init"] を設定し、ローカルの *-machine イメージをビルドします。openrc だけをインストールし、BusyBox の /sbin/init を使用すると、起動直後に終了することがあります。
• Ubuntu/Debian マシンでは、必要に応じて systemd、dbus、sudo、SSH／ネットワークツールを追加し、systemd のターゲットを設定して、ローカルの *-machine イメージをビルドします。
• Apple Container 1.2 以前では、OpenRC、マスクされたパス、読み取り専用パスに関するエラーを恒久的なカスタムイメージの回避策にする前に、アップグレードしてください。

安全ルール

次の操作を行う前に、ユーザーに確認してください。

• sudo の実行、インストール、アップグレード、アンインストール、または DNS リゾルバーのエントリの変更。
• 全体のクリーンアップ：container prune、container image prune、container volume prune、container network prune、またはすべてのリソースの削除。
• 現在のタスク用に作成されていない、名前付きマシン、ボリューム、イメージ、コンテナの削除。
• ~/.ssh/config の編集、ホストのファイアウォール／VPN 設定の変更、またはプロジェクトディレクトリを超えるバインドマウントの拡張。
• セキュリティ制御を無効化または弱めるカーネル引数の指定。--kernel-arg は、通常のアプリケーション設定ではなく、文書化されたカーネルレベルの要件に限って使用してください。
• --masked-path または --read-only-path への NONE の指定。これは制限を追加するのではなく、ランタイムのセキュリティ既定値を解除するためです。

強制削除または container kill の前に、正常な停止（container stop、container machine stop）を優先してください。

実用的な既定値

一般的なプロジェクト用シェル：

container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash

イメージのビルドと実行：

container build -t local/app:dev .
container run --rm -p 8080:8080 local/app:dev

長時間稼働するマシン：

container machine create docker.io/library/alpine:latest --name dev --set-default --cpus 4 --memory 8G
# Run the first command from a real terminal so initial user setup has a host PTY.
container machine run -n dev -- /bin/sh -c 'whoami; pwd; echo "$HOME"'
container machine stop dev

現在の重要な動作

• container system property get、set、clear は 1.0 で削除されました。デフォルトには ~/.config/container/config.toml を使用し、有効な設定の確認にのみ container system property list を使用してください。
• Apple の署名済みインストーラーは CLI を /usr/local/bin/container に配置します。新しいシェルで container が見つからない場合は、そのパスを直接確認してください。
• Apple Container 1.3 では、レジストリの --scheme auto 値が削除されました。現在のリリースで使用できるのは https（デフォルト）または明示的な http のみです。HTTP は、意図的に信頼するローカルレジストリに限って使用してください。
• Apple Container 1.3.1 と 1.4.1 には、細工された識別子、イメージレイヤー／レイアウト、レジストリ認証、ホストファイルへのアクセスに関するセキュリティ修正が含まれています。さらに Apple Container 1.5.0 では、Kubernetes ゲストから受け取った kubeconfig 値をホストの kubeconfig にマージする前にサニタイズします。基本的なスモークテストに合格したという理由だけで、信頼できない OCI 入力や実験的な Kubernetes に古いランタイムを使用しないでください。
• container build は BuildKit ビルダーを実行したままにする場合があります。検証タスクでランタイムプロセスを残してはならない場合は、container builder status で状態を確認してから、container builder stop と container builder delete を使用してください。
• Apple Container 1.2.1 では container build --ssh default が追加されました。プライベートなビルド依存関係にはこれを使用し、SSH キーをビルドコンテキストやイメージにコピーしないでください。
• ホストからコンテナーへのトラフィックには、通常 -p/--publish を使用してください。失敗する場合は、コンテナー内でアプリが 0.0.0.0 をリッスンしていることを確認してください。
• Unix ソケットは、方向に応じて選択してください。ホストにすでに存在するソケットをコンテナー内にマウントするにはバインドマウント（-v）を使用します。コンテナー内のプロセスがソケットを作成し、ホストからアクセスする必要がある場合は、--publish-socket host_path:container_path を使用してください。root 以外のクライアントでは、両方のエンドポイントの所有者とモードを確認してください。Apple Container 1.1 では、root 以外のユーザーによるソケットマウントへのアクセスが修正されました。
• Apple Container 1.1 では container cp の相対ローカルパスも修正されました。古いバージョンでは、正しい相対パスの調査に時間を費やすのではなく、絶対パスを使用するかアップグレードしてください。
• Apple Container 1.2 では、信頼できないイメージの裸の ENV エントリーが、同名のホスト変数を暗黙的にコピーすることを防止します。それでも継承は明示してください。ホストの値を引き継ぐ意図がある場合に限り -e NAME を使用し、再現可能な実行には KEY=value、環境変数ファイル、またはシークレット機構を優先してください。
• 繰り返し使用する --kernel-arg key=value は、カーネル／セキュリティ／デバッグ上の要件がある場合に限って使用し、cat /proc/cmdline で有効なコマンドラインを確認してください。アプリケーション設定には使用せず、lsm=landlock などのセキュリティ上のデフォルトを安易に置き換えないでください。
• 1.5.0 までのバージョンでは、インストール済みの container run --help で確認したところ、container run --stop-signal はありません。再利用可能なデフォルトにはイメージ内の STOPSIGNAL を設定するか、オペレーターが選択したシグナルには container stop -s SIGNAL を使用してください。
• --masked-path と --read-only-path は、run と create における実験的な追加の分離制御です。インストール済みのヘルプで利用方法を確認し、パスの追加を優先してください。明示的な承認なしに NONE を指定してランタイムのデフォルトをクリアしないでください。
• container clean <running-container...> は、各コンテナーのルートファイルシステムと名前付きボリュームマウントから未使用のファイルシステム領域を回収します。対象範囲は指定したコンテナーに限られ、実行中のコンテナーが必要です。グローバルなプルーンコマンドの代わりにはなりません。
• container system status では 1.4.1 でホスト、クライアント、パス、リソースの追加フィールドが導入され、その形式は 1.5.0 でも維持されています。構造化出力はフィールド名で処理し、従来の形式に依存せず、フィールドの追加を許容してください。
• 1.5.0 以降では、イメージの ENTRYPOINT が空でもコマンド引数が実行されます（ENTRYPOINT [] のイメージでローカルに確認済みです）。古いランタイムでそのようなイメージに対するコマンドが無視されるように見える場合は、イメージをラップしたりエントリーポイントを書き換えたりせず、アップグレードしてください。
• Apple Container 1.5.0 では、localhost の DNS 変更後にコンテナーの外向き通信が失われる問題と、シンボリックリンクされた祖先ディレクトリ配下のビルドコンテキストファイルが除外される問題が修正されました。古いランタイムでいずれかの症状が発生した場合、ネットワークを再設計したりシンボリックリンクツリーからファイルをコピーしたりするのではなく、アップグレードの合図とみなしてください。
• ワークフローでそれ以外の動作が確認されていない限り、名前付きボリュームは単一のコンテナーにのみアタッチできるものとして扱ってください。同じ名前付きボリュームを複数の実行中コンテナーに同時にアタッチできると想定しないでください。
• コンテナーからホストへのトラフィックには、Docker の特殊なホストエイリアスは使用されません。localhost DNS ドメインを設定してください。

sudo container system dns create host.container.internal --localhost 203.0.113.113

これによりプライベートリレーが無効になることがあり、再起動後にパケットフィルタールールを再作成する必要が生じる場合があります。

• container network のユーザー定義ネットワークには macOS 26 以降が必要です。コンテナ名の名前解決は現在、デフォルトネットワークでのみ機能します。カスタムネットワークでは、Docker 形式のサービスディスカバリーを前提とせず、検査で取得した IP を使用してください。
• container compose はありません。信頼できるシンプルなスタックを、明示的なビルド／実行／準備完了確認／停止コマンドに置き換えるか、Compose のセマンティクスが必要な場合は Compose 対応のランタイムを使い続けてください。
• ネットワークが機能していたのに、VPN またはエンドポイントセキュリティの変更後に失敗する場合は、アプリケーションコードを変更する前に vmnet／VPN のルーティングを疑ってください。
• マシンの初回コマンドでは、ユーザーのセットアップが完了するまで、実際のホストターミナルが必要になる場合があります。ヘッドレスでの初回実行が Operation not supported by device で失敗する場合は、PTY から初期化を再試行してください。その後の非対話型 machine run ... -- command 呼び出しはスクリプト化できます。ヒアドキュメントや無人実行ジョブに -i を追加しないでください。

参考資料

• 一般的な開発、ビルド、ネットワーク、レジストリ、ボリューム、マシン、ファイルシステム領域の解放、実験的な Kubernetes の手順については、references/workflows.md を参照してください。
• サービスの起動、DNS、VPN、vmnet、ビルダー、Rosetta、ポート公開、またはマシンモードで問題が発生した場合は、references/troubleshooting.md を参照してください。
• 必要なワークフローがわかった後の簡潔なコマンド一覧については、references/commands.md を参照してください。