クイックスタート
このページでは、Takumi Agent を Mac デバイスにセットアップする手順を説明します。作業は次の 3 つです。
- 管理コンソールでの登録キーの発行
- Mac デバイスでのインストーラーパッケージの実行
- Mac デバイス上に表示されるセットアップウィンドウと macOS のダイアログでの承認
これらを完了すると、Mac デバイス上で Takumi Agent が有効になります。ターミナルでの作業は必要ありません。
動作要件
- Apple シリコン搭載の Mac
- macOS 13（Ventura）以降
- 管理者アカウント（パッケージのインストール、デバイスの登録、この Mac のデバイス証明書の信頼に必要）
デバイス上で要求される操作
セットアップの途中で、Mac デバイス上には次の順にシステムのダイアログが表示され、承認が求められます。
- デバイスの管理者パスワード：エージェントのインストール時に必要
- 通知の許可（任意）：エージェントによる保護が中断された際に、Mac デバイス上で通知を表示するために必要
- デバイス証明書を信頼するための管理者の資格情報
- システム拡張の承認：システム設定で許可し、続けてデバイスの管理者パスワードを入力する
- 「TakumiAgent Would Like to Add Proxy Configurations」：パッケージのダウンロードなどの通信を Takumi Guard に通すために必要
- 「… would like to filter network content」：Takumi Guard を迂回して対象レジストリへ直接接続する通信をブロックする（エグレスロック）ために必要
ステップ 1: インストーラーパッケージの取得
最新のインストーラーパッケージ takumi-agent-latest.pkg をダウンロードします。特定のバージョンは https://shisho.dev/releases/takumi-agent-<version>.pkg からダウンロードできます。初期セットアップが完了した後は、エージェントにより自動で更新が適用されます（エージェントの更新を参照）。
ステップ 2: 登録キーの発行
管理コンソールで Endpoint → 登録キー → 登録キーを作成 を開きます。
表示されるモーダルで、ラベル・最大アクティ ベーション数・有効期間を設定します。下部のトグルでは、発行するキーで登録したデバイスについて、Takumi Guard の保護対象とするエコシステムを設定できます。すべてのエコシステムを有効にした場合、Takumi Guard の機能は制限されません。各設定についてはデバイスの管理を参照してください。
作成 をクリックすると、発行されたキー（tg_enroll_… で始まる形式）が表示されます。
発行されたキーは発行直後にこの画面で一度だけ表示され、以降は管理コンソール上で確認できません。後ほどデバイス上でのセットアップで必要になるため、その場でコピーしてください。
登録キーの発行および表示には、オーナー または Takumi 管理者 のロールが必要です（ロールと権限を参照）。登録キーを作成 のボタンが表示されない場合は、組織のオーナーに依頼してください。
ステップ 3: デバイス上でのエージェントのインストール
インストーラーパッケージをダブルクリックし、管理者パスワードを入力します。インストール先は常に /Applications です。
インストーラーはアプリのほかにバックグラウンドサービスを構成するため、誰もデバイスにログインしていない間も保護は動き続けます。
Mac のデスクトップにユーザーがログインしている状態で初回インストール を行った場合、インストーラーの終了時にセットアップウィンドウが開きます。それ以外の場合は、次回ログイン時に開くか、/Applications から Takumi Agent を起動してください。
コマンドラインを用いたインストール
Takumi Agent のインストールは、コマンドラインからも実行できます。次のようにパッケージをダウンロードし、登録キーを installer の環境変数 TAKUMI_AGENT_ENDPOINT_ENROLLMENT_TOKEN で渡します。
curl -fLO https://shisho.dev/releases/takumi-agent-latest.pkg
sudo TAKUMI_AGENT_ENDPOINT_ENROLLMENT_TOKEN=tg_enroll_… installer -pkg takumi-agent-latest.pkg -target /
コマンドラインで初回インストールを行った場合、インストール中にデバイスが自動的に登録されます。セットアップウィンドウはステップ 4 を飛ばし、ステップ 5 から表示されます。渡した登録キーが拒否された場合もインストールは完了し、セットアップウィンドウが通常どおりステップ 4 で登録キーを求めます。
ステップ 4: 登録キーの入力
ステップ 2 で発行した登録キーをセットアップウィンドウに貼り付けます。これにより、Mac デバイスが組織のデバイスとして登録されます。
ステップ 5: デバイス証明書の信頼
macOS が管理者の資格情報を求めます。この操作は、Mac デバイスのデバイス証明書をシステムキーチェーンで信頼させるために必要です。
macOS はこの操作に管理者の直接の承認を求めるため、インストーラーが自動で行うことはできません。この手順が完了するまで、Mac デバイス上では 未保護、管理コンソール上では 保護なし と表示され、捕捉対象のインストールは フェイルクローズ で失敗します。つまり、対象エコシステムのパッケージはデバイス上にダウンロードできません。
ダイアログを閉じるなどしてセットアップが中断された場合は、次回アプリの起動時に再度ダイアログが表示されます。また、メニューバーにはセットアップを続行するための 「セットアップを完了…」 ボタンが表示されます。
管理者でないユーザーは、この手順を完了できず、デバイスの登録もできません（アプリ上にもその旨が表示されます）。デバイスの管理者が Takumi Agent を開くまで、デバイスは未保護のままです。
ステップ 6: システム拡張・プロキシ構成・フィルタの承認
続いて、次の 3 つの承認が求められます。3 つとも承認してください。
システム拡張の許可
macOS が システム拡張の許可 を求めます。これは、Takumi Agent がパッケージレジストリへの通信を扱うために必要な許可です。システム設定を開く をクリックすると、ログイン項目と機能拡張 の ネットワーク機能拡張 の一覧が表示されます。TakumiAgent のトグルをオンにし、管理者パスワードを入力してください。
ダイアログを閉じるなどしてセットアップが中断された場合は、システム設定 → 一般 → ログイン項目と機能拡張 で カテゴリ別 を選択し、ネットワーク機能拡張 の横の ⓘ をクリックすると再開できます。
プロキシ構成の許可
次に 「TakumiAgent Would Like to Add Proxy Configurations」 というダイアログが表示されるので、許可 をクリックしてください。これは、対象エコシステ ムのパッケージをインストールする際の通信を、Takumi Guard のプロキシ経由にするために必要な操作です。許可するまで、通信は検査されません。
コンテンツフィルタリングの許可
最後に、Takumi Agent に ネットワークコンテンツのフィルタリング を許可するかどうかを尋ねるダイアログが表示されます。これはエグレスロックのための許可です。エグレスロックは対象レジストリへの直接の接続をブロックし、Takumi Guard を迂回したパッケージのダウンロードを防ぎます。許可 をクリックしてください。承認しなくても捕捉は動作しますが、承認するまで Mac デバイスには 要対応 と表示されます。
セットアップウィンドウのチェックリストは、各手順の完了が確認されるたびに更新されます。各項目の意味は次のとおりです。
| チェックリストの項目 | 意味 |
|---|---|
| 機能拡張の承認 | システム拡張が承認されている |
| ネットワークフィルタ | ネットワークフィルタが有効化されている |
| インストールの検査 | バックグラウンドサービスがパッケージのインストールを検査している |
3 つの項目がすべて完了しているにもかかわらず 「この Mac はまだ保護されていません」 と表示される場合は、トラブルシューティングを参照してください。
ダイアログを閉じてしまった場合は、「承認ダイアログを再表示」 または 「システム設定を開く…」 から再度表示できます。ネットワークフィルタがオフになっている場合は 「ネットワークフィルタをオンにする」 ボタンが、コンテンツフィルタの承認を見送った場合はパネルに 「エグレスロックを有効にする…」 が表示されます。
ステップ 7: メニューバーの確認
セットアップが完了すると、Mac デバイスのメニューバーに Takumi のパンダのアイコン 
が表示され、その隅に状態を示すバッジが付きます。緑の丸は保護中を表します。その他の状態についてはデバイスの状態を参照してください。
アイコンをクリックするとパネルが開き、保護の状態と保護対象ごとの詳細が表示されます。Guard（展開するとエコシステムごとに表示）、コンテナ、エグレスロック、識別情報、ヘルス の 5 行が並び、利用者の操作で解消できる事象には、行ごとに操作用のボタンが表示されます。その下には、エージェントのバージョンと最終チェックイン時刻、「今すぐチェックイン」 ボタン、アプリウィンドウを開く 「Takumi Agent を開く」 ボタン、ヘルプ、「ステータスアイコンを終了」（保護は継続します）があります。
パネルの表示言語は、Mac の言語設定（Takumi Agent 向け）に従います（現在は英語と日本語に対応しています）。
ステップ 8: 管理コンソールでの確認
登録が完了したデバイスは、数秒以内に管理コンソール上に表示されます。その後は、約 5 分ごとに最新の状態が報告されます。
左のナビゲーションバーで Endpoint を選択すると、デバイス タブが表示されます。セットアップが完了したデバイスをクリックし、表示される詳細パネルで 保護中 と表示されていることを確認してください。
実際のパッケージマネージャーでも保護を確認できます。パッケージマネージャーを個別に設定する必要はありません。例として、npm でテスト用パッケージのインストールを試します。
npm install @panda-guard/test-malicious
セットアップ前に開いたターミナルは、まだデバイス証明書を信頼していません。この確認は、新しいターミナルウィンドウで実行してください。
npm が 403 Forbidden を返せば、Takumi Guard がリクエストを検査してブロックしています。それ以外の結果になった場合は、メニューバーのパネルを開いてデバイスの状態を確認してください。
Go modules でも、Guard のテスト用モジュールを使って、パッケージマネージャーの設定を変更せずに保護が有効であることを確認できます。こちらも 403 Forbidden が返されます。
cd $(mktemp -d) && go mod init verify-takumi-guard && go get github.com/flatt-security/hola-takumi-go@v0.1.0
セットアップ完了後の追加作業
デバイス上のセットアップが完了したら、ターミナル、IDE、AI コーディングエージェントを再起動してください。
また、コンテナなど隔離された環境で開発する場合は、コンテナでデバイス証明書を信頼させる設定が一度だけ必要です。開発環境ごとの設定方法については、Takumi Agent を使った開発を参照してください。
更新
エージェントは自動で更新されます。詳細についてはデバイスの管理を参照してください。
アンインストール
Mac デバイス上で Takumi Agent のアプリ を削除するだけでは、システム拡張とネットワーク設定が残ります。アンインストールの手順についてはアンインストールを参照してください。