メインコンテンツまでスキップ
Markdown で見る

Takumi Agent を使った開発

Takumi Agentをインストールした Mac デバイス上では、別途設定せずとも対応エコシステムのパッケージのインストールが Takumi Guard を経由します。

その代わり、Takumi Guard 機能がデバイス内で正常に作動するにはデバイス証明書が信頼されている必要があります。

対象レジストリからパッケージをダウンロードする際に使用するツールは、すべてこのデバイス証明書を信頼している必要があります。このページでは、信頼の設定が自動で行われる場合と、手順が必要な場合について説明します。

デバイス証明書を信頼していないツールを用いたパッケージのダウンロードはブロックされます。

インストール後のターミナルと IDE の再起動​

Takumi Agent は、インストール完了以降に新しく開かれるシェル、新しく起動されるアプリに信頼設定を適用します。インストール完了以前から既に開かれていたシェル・プログラムは、信頼設定が適用されず、パッケージのダウンロード等がブロックされます。インストール後は次の対応をしてください。

  • 新しいターミナルウィンドウを開く。セットアップ前に開いたタブやウィンドウには設定が反映されていません。
  • 起動中の IDE と AI コーディングエージェントを終了して開き直す（VS Code、Cursor、JetBrains の IDE、Claude Code など）。内蔵ターミナルはアプリの環境を引き継ぐため、古い IDE の中で新しいタブを開くだけでは足りません。
  • 自分で起動したバックグラウンドサービスを再起動する（ローカルのビルドサーバーなど）。

Mac 上のツール​

Takumi Agent はインストール時、信頼する証明書を独自で設定しているツールに信頼設定を適用するために、下記の環境変数を設定します。

環境変数使用するツール
NODE_EXTRA_CA_CERTSnode、npm、npx、yarn、pnpm、corepack、bun
REQUESTS_CA_BUNDLEpython、pip、pipx、poetry、pdm、conda
SSL_CERT_FILEruby、CocoaPods、uv、curl、wget
GEMRCgem、bundler
PHP_INI_SCAN_DIRphp、composer
info

Go は信頼する証明書の設定については macOS のキーチェーンに依存するため、別途設定せずともデバイス証明書を信頼します。

また、deno は独自の証明書ストアを持ちますが、Takumi Agent は現在自動で設定変更を行いません。必要に応じて DENO_TLS_CA_STORE=system を設定し、macOS のキーチェーンに依存するよう設定してください。

これらの値は、システムのシェル起動ファイルが読み込む /etc/takumi-agent-endpoint/env.sh で設定されます。証明書そのものは、トラストバンドル /Library/Application Support/takumi-agent-endpoint-trust/bundle.pem に格納されています。

別の事情でこれらの環境変数を設定している場合

ユーザー自身で起動ファイルにて記述（たとえば ~/.zshrc の export NODE_EXTRA_CA_CERTS=…）することで上記いずれかの環境変数を設定している場合、Takumi Agent がインストール時に設定した環境変数値が上書きされ、そのシェルから起動したツールはデバイス証明書を信頼しません。この場合、パネル（インストール後に Mac デバイスのメニューバーに表示される Takumi のパンダのアイコンメニューバーの Takumi のパンダ を選択すると表示されます）にそのファイル名が表示されます。

Takumi Agent を正常に動作させるには、自分で該当環境変数を設定している行を削除するか、/etc/takumi-agent-endpoint/env.sh にある値に合わせて設定する必要があります。

コンテナ・仮想マシン内での開発​

コンテナ・仮想マシン内で開発を行う場合、用いるツールやランタイムに応じて必要な対応が異なります。

コンテナ​

コンテナ内で開発する場合、実行中のコンテナ内でパッケージをダウンロードする際にデバイス証明書の信頼が必要となります。

macOS 上のコンテナランタイムでは独自に起動された VM 内でコンテナを実行しており、したがって VM 内でもデバイス証明書の信頼設定が適用されている必要があります。Docker Desktop、OrbStack、Rancher Desktop 等のランタイムは、起動時に macOS のキーチェーンを読み込むため、別途設定せずとも正常に動作します。しかし、Colima、Lima、Podman、Multipass、minikube 等の macOS キーチェーンを読み込まないランタイムに関しては、コンテナページにて提供されるセットアップコマンドの実行が必要になります。これらのコマンドを実行することにより、VM 内にトラストバンドルがインストールされます。

Takumi Agent の初期セットアップが完了した直後、あるいはデバイス証明書が最後に変わった以前からランタイムを起動していた場合は、ランタイムを終了して開き直してください。どのランタイムで必要かは、パネルとコンテナページに表示されます。

警告

ランタイム内の個別のマシンを再起動するだけでは、デバイス証明書の設定は反映されません。ランタイム自体を再起動してください（OrbStack の場合は orb stop の後に orb start）。

警告

Apple Container（container コマンド）はキーチェーンを読み込まず、独自の証明書を渡す設定もまだないため、現在 Takumi Agent では対応していません。

コンテナはそれぞれ独自のトラストストアを持つため、コンテナ内でも信頼設定を適用する必要があります。コンテナ内でデバイス証明書が正常に信頼されるには、起動時にトラストバンドルを設置する必要があります。そのため、コンテナ内でパッケージをインストールする際には、コンテナページで表示されるコマンドスニペットの実行が必要になります。

仮想マシン​

完全な仮想マシン（vfkit、UTM、Parallels、VMware Fusion、VirtualBox、QEMU 等）の場合、ゲスト OS 内の設定はユーザー自身の管理下であるため、ゲスト内に貼り付けるコマンドをコンテナページにて取得し、実行してください。

リポジトリに設定を含めない​

caution

トラストバンドルファイルは、Takumi Agent をインストールした Mac デバイス上にのみ存在する想定です。 コンテナの信頼設定は手元のマシンに置き、チームでコミットするファイルには含めないでください。

コンテナの起動方法ごとに、バンドルファイルをコミットせずに指定する推奨方法を下記に整理します。

コンテナの起動方法設置・設定方法
docker runコマンドライン引数にてトラストバンドルのパスをマウント指定で（-v）、トラスト設定関連の環境変数は env 指定で（-e で直接指定、または --env-file ~/.takumi/container.env 等でファイルを指定）指定してください。
Docker Compose ファイルCompose ファイルと同ディレクトリ階層にて override ファイル（compose.override.yaml）を設置し、コンテナページから取得可能な compose 専用スニペットをペースト（この時、デフォルトで指定されている app サービス名は compose ファイルに記載されたユーザーのサービス名に合わせる）してください。Compose がこのファイルをマージするのは -f を付けずに docker compose を実行したときのみのため、-f を指定して使う場合や、あるいは同ディレクトリ階層にて既に別の override ファイルをコミットしている場合は、もう一つ -f を指定し、新規の override ファイルを指定してください。当該 override ファイルは git からは .git/info/exclude 等で除外してください
docker buildDockerfile 等にてMac 上でのイメージのビルドを参照してください
info

Docker Desktop は初期設定では /Library を共有しないため、マウントするには、バンドルのフォルダ（/Library/Application Support/takumi-agent-endpoint-trust）を Settings › Resources › File sharing にて追加する必要もあります。コンテナページは Docker の設定を読み込み、追加済みかどうかを表示します。

Mac 上でのイメージのビルド​

docker build 中に発生する対応パッケージエコシステムのダウンロード（例：RUN npm install）でもデバイス証明書の信頼の設定が必要となります。

この場合、トラストバンドルファイルをリポジトリ上に保管せずに指定するための推奨手法は以下の 2 通りです。

トラストバンドルファイルをローカルにとどめる方法： git レポジトリ等にコミットしない、ローカル専用の Dockerfile を用意する手法です。コンテナページから取得可能な Dockerfile 用スニペットは、カスタムのビルドコンテキストからバンドルを取得します。

# docker build --build-context takumi="/Library/Application Support/takumi-agent-endpoint-trust" .
COPY --from=takumi bundle.pem /takumi/trust.pem
ENV SSL_CERT_FILE=/takumi/trust.pem
ENV NODE_EXTRA_CA_CERTS=/takumi/trust.pem
ENV REQUESTS_CA_BUNDLE=/takumi/trust.pem

この takumi ビルドコンテキストは Takumi Agent をインストールした Mac デバイスにしか存在しないため、これらの行を含む Dockerfile は、CI 環境や Takumi Agent をインストールしていないデバイス内ではビルドが失敗します。コミットしないローカルの Dockerfile で、かつビルダーステージにのみ使ってください。

caution

ビルダーステージ以外で使うと、ENV の行が最終イメージに残ります。

Takumi Agent インストール済み環境のみで作動する行をコミットする方法: BuildKit のシークレットマウントは、シークレットが渡されなければスキップされるため、下記のような記述を Dockerfile に含めることで、CI 環境や Takumi Agent がインストールされていないデバイス内では環境変数の設定などが実行されない処理が指定できます。

RUN --mount=type=secret,id=takumi,target=/takumi/trust.pem \
    if [ -f /takumi/trust.pem ]; then \
      export SSL_CERT_FILE=/takumi/trust.pem NODE_EXTRA_CA_CERTS=/takumi/trust.pem REQUESTS_CA_BUNDLE=/takumi/trust.pem; \
    fi; \
    npm ci

Mac デバイス上では docker build --secret id=takumi,src="/Library/Application Support/takumi-agent-endpoint-trust/bundle.pem" . で build することでデバイス証明書がインストールされ、CI やほかのデバイス上ではこれまでどおり build し、デバイス証明書等はインストールされず、証明書がイメージのレイヤーに書き込まれることもありません。

info

この手法の場合、git リポジトリ等にコミットされるファイルに Takumi 固有の記述（例：/takumi などのパス指定）が加わるため、開発チーム内で合意をとった上で対応してください。

レジストリの認証情報と公開​

Takumi Guard 機能はパッケージのインストールに対して判定・ブロックを実施します。Takumi Agent をインストールした Mac デバイスは、対象となるエコシステムのパッケージインストールのリクエスト（パッケージのメタデータとパッケージ本体）に Takumi Guard の組織トークンを認証情報として含めて送ります。この時、Takumi Agent インストール前にユーザー自身がパッケージレジストリの認証情報などを指定していた場合、Takumi Guard の組織トークンに置き換えられます。

パッケージのインストール時以外の挙動に Takumi Agent は関与しません。npm publish、 gem push、npm login、npm deprecate、npm owner 等の、パッケージの新規公開やアカウント関連の操作などの操作は Takumi Guard の組織トークンは認証情報として含まれず、もし事前にパッケージレジストリの認証情報などが前から設定されていた場合、そのまま認証情報として含まれて送られます。また、レジストリの Web サイトや API、pip-audit や composer audit などの脆弱性の照会には、レジストリ自身が応答します。

Takumi Guard の組織トークンへの置き換えの挙動により、公開レジストリでホストされているプライベートパッケージ（例：registry.npmjs.org 上のプライベートパッケージ）からのパッケージのインストールリクエストが拒否される可能性があります。これは、仮にプライベートパッケージにアクセスするために認証情報が必要とされる場合、本来必要な認証情報が Takumi Guard の組織トークンに置き換えられるためです。そうしたパッケージは、Takumi Agent がインストールされていない CI からインストールするか、Takumi Agent による通信の捕捉が発生しないエンドポイント上でプライベートレジストリをホストすることで迂回できます。

パネルにプログラム名が表示された場合​

特定のツールが Takumi Agent のデバイス証明書を信頼していない場合、メニューバーのパネルに該当するプログラム名が表示されます。表示ごとの対処についてはトラブルシューティングを参照してください。

に最終更新