ランタイム

Kobune は、プロジェクトごとに選択したバックエンドでコンテナを実行します。

toml

[runtime]
default = "docker"   # または "apple"

kobune doctor は、プロジェクトが使用するランタイムと、他に利用可能なランタイムを表示します。

console

$ kobune doctor
│ …
│ ✓  container runtime            apple 1.2.1
│ ✓  Docker (available)           docker 29.4.0
│ …

Docker

既定のランタイムで、サポートも充実しています。Kobune は bollard を通じて Docker API を直接利用し、docker CLI は呼び出しません。そのため API に到達できれば動作し、Docker Desktop、OrbStack、colima のいずれでも構いません。

ポートは 127.0.0.1 上の動的に選択されたポートにフォワードされます。 0.0.0.0 にバインドすることはありません。同一ネットワーク上の他者から開発環境が見えてしまうためです。

サービス名はネットワークエイリアスによって解決されるため、同じ workspace 内のどのコンテナからでも db:5432 でアクセスできます。

Apple Container

macOS 26 以降と、サービスの起動が必要です。

console

$ container system start

各コンテナが 192.168.x.x 上の専用 IP アドレスを持つため、ホストへの publish が不要で、ポートの衝突も発生しません。プロキシはコンテナへ直接転送します。

選ぶ前に把握しておくべき違いが 3 点あります。

コンテナ間の名前解決ができない

Apple Container にはネットワークエイリアスもコンテナ間 DNS も存在しません。コンテナのネームサーバはネットワークのゲートウェイであり、コンテナ名に対しては NXDOMAIN を返します。db:5432 では接続できません。

代わりに Kobune が、対象サービスの IP アドレスを注入します。

KOBUNE_HOST_DB = 192.168.64.7

そのため、次のように記述します。

const db = process.env.KOBUNE_HOST_DB ?? 'db'

depends_on の指定が必要です

アドレスはサービスの起動時に取得するため、まだ起動していないサービスに対応する変数は作成されません。depends_on を指定してください。 Kobune が正しい順序で起動します。

変数を未設定のままにしているのは意図的です。解決できないホスト名を渡すと、存在しない DNS の問題を調査することになります。変数が存在しなければ、起動順序の問題であると判断できます。

サービスの URL は /etc/hosts を経由する

--add-host に相当する機能がないため、そのフラグが書き込むはずのファイルを Kobune が生成し、/etc/hosts としてマウントします。workspace のホスト名はネットワークのゲートウェイ、つまりホストに向けられます。コンテナからはホストのループバックが見えないため、プロキシに到達できる経路はここだけです。

プロキシがそのアドレスで待ち受けている必要があり、80 と 443 に置けるのは launchd だけです。そのソケットを plist に書き込むのは kobune setup なので、 Apple Container を入れるより前にセットアップしたマシンでは kobune setup を実行し直す必要があります。該当する場合は kobune doctor が指摘します。

console

$ kobune doctor
✗ reachable from containers  the proxy is not listening on 192.168.64.1, …

すべてが 1 つのネットワークを共有する

Apple Container では、コンテナは 1 つのネットワークにしか参加できず、 network connect に相当する機能もありません。workspace ごとにネットワークを分けると、scope = "project" のサービスは最初に起動した worktree に紐づき、他の worktree からアクセスできなくなります。これは、その scope が防ぐために存在する状況そのものです。

そのため、すべてのコンテナが既定のネットワークに参加します。worktree 同士はネットワークレベルでは分離されません。1 人が 1 台のマシンで行うローカル開発としては許容できる制約ですが、分離を前提としている場合は把握しておいてください。

その他の相違点

名前付きボリュームがありません。 Kobune は ~/.kobune/volumes/<project>/ へのバインドマウントに置き換え、同等の永続性を確保します。
kobune doctor は、このランタイムを使用している場合に「Docker Desktop を起動」ではなく container system start を提示します。

どちらを選ぶべきか

特別な理由がなければ Docker を推奨します。ネットワークエイリアス、名前付きボリューム、worktree ごとのネットワーク分離が利用できます。

Apple Container が適しているのは、Docker Desktop を常駐させずコンテナごとに軽量な VM を使いたい場合で、かつサービス間通信を KOBUNE_HOST_* で記述でき、 worktree 間のネットワーク分離が不要なケースです。

マシンごとに使い分ける

上記の設定はリポジトリで管理するため、クローンしたどのマシンでも同じ内容になります。「このノート PC には Docker Desktop があり、あちらは Apple Container を使う」という場合は、代わりに ~/.kobune/config.toml に書きます。これはマシンに属するファイルで、kobune.toml より先に読み込まれます。

toml

# ~/.kobune/config.toml
[runtime]
default = "apple"

これでそのマシン上のすべてのプロジェクトをまとめて設定できます。kobune.toml から [runtime] を省けばこちらの指定が使われ、書いてあればそちらが優先されます。リポジトリで管理しているファイルのほうが限定的だからです。

マシン単位ではなくクローン単位で変えたい場合は、kobune.toml の隣に置く kobune.local.toml が同じ役割を果たし、いちばん最後に読み込まれます。どちらも層で説明しています。値がどの層から来たかは kobune config show で確認できます。

Firecracker

対応予定ですが、まだ使えません。KVM を必要とするため動作するのは Linux ホスト上だけで、macOS では動きません。開発に使える Linux マシンを用意できていない、というのが現状です。

Runtime トレイトはこの種の差異を吸収するために存在しており、Apple Container の対応によってその設計が機能することは確認できました。バックエンドはプロキシの転送先アドレスを返すだけで、プロキシはどのバックエンドが返したものかを知りません。3 つ目を追加しても、トレイトより上は変わりません。