# クイックスタート {#quickstart}

このページでは、[Takumi Agent](/docs/ja/t/endpoint/index.md) を Mac デバイスにセットアップする手順を説明します。作業は次の 3 つです。

- 管理コンソールでの登録キーの発行
- Mac デバイスでのインストーラーパッケージの実行
- Mac デバイス上に表示されるセットアップウィンドウと macOS のダイアログでの承認

これらを完了すると、Mac デバイス上で Takumi Agent が有効になります。ターミナルでの作業は必要ありません。

## 動作要件 {#prerequisites}

- **Apple シリコン搭載の Mac**
- **macOS 13（Ventura）以降**
- **管理者アカウント**（パッケージのインストール、デバイスの登録、この Mac のデバイス証明書の信頼に必要）

## デバイス上で要求される操作 {#prompts}

セットアップの途中で、Mac デバイス上には次の順にシステムのダイアログが表示され、承認が求められます。

1. **デバイスの管理者パスワード**：エージェントのインストール時に必要
2. **通知の許可**（任意）：エージェントによる保護が中断された際に、Mac デバイス上で通知を表示するために必要
3. **デバイス証明書を信頼するための管理者の資格情報**
4. **システム拡張の承認**：システム設定で許可し、続けてデバイスの管理者パスワードを入力する
5. **「TakumiAgent Would Like to Add Proxy Configurations」**：パッケージのダウンロードなどの通信を Takumi Guard に通すために必要
6. **「… would like to filter network content」**：Takumi Guard を迂回して対象レジストリへ直接接続する通信をブロックする（エグレスロック）ために必要

## ステップ 1: インストーラーパッケージの取得 {#download}

最新のインストーラーパッケージ [takumi-agent-latest.pkg](https://shisho.dev/releases/takumi-agent-latest.pkg) をダウンロードします。特定のバージョンは `https://shisho.dev/releases/takumi-agent-<version>.pkg` からダウンロードできます。初期セットアップが完了した後は、エージェントにより自動で更新が適用されます（[エージェントの更新](/docs/ja/t/endpoint/features/managing-devices.md#updates)を参照）。

## ステップ 2: 登録キーの発行 {#enroll-key}

管理コンソールで **Endpoint → 登録キー → 登録キーを作成** を開きます。

<img src={require("./installation-step2-enrollment-keys.png").default} alt="管理コンソールの登録キー一覧" className="zoomable" />

表示されるモーダルで、ラベル・最大アクティベーション数・有効期間を設定します。下部のトグルでは、発行するキーで登録したデバイスについて、Takumi Guard の保護対象とするエコシステムを設定できます。すべてのエコシステムを有効にした場合、Takumi Guard の機能は制限されません。各設定については[デバイスの管理](/docs/ja/t/endpoint/features/managing-devices.md#enrollment-keys)を参照してください。

<img src={require("./installation-step2-create-key-dialog.png").default} alt="登録キーの作成ダイアログ" width="460" className="zoomable" />

**作成** をクリックすると、発行されたキー（`tg_enroll_…` で始まる形式）が表示されます。

:::warning
発行されたキーは発行直後にこの画面で一度だけ表示され、以降は管理コンソール上で確認できません。後ほどデバイス上でのセットアップで必要になるため、その場でコピーしてください。
:::

登録キーの発行および表示には、**オーナー** または **Takumi 管理者** のロールが必要です（[ロールと権限](/docs/ja/c/iam/permission.md)を参照）。**登録キーを作成** のボタンが表示されない場合は、組織のオーナーに依頼してください。

## ステップ 3: デバイス上でのエージェントのインストール {#install-pkg}

インストーラーパッケージをダブルクリックし、管理者パスワードを入力します。インストール先は常に `/Applications` です。

<img src={require("./installation-step3-installer.png").default} alt="Takumi Agent のインストーラー" width="640" className="zoomable" />

インストーラーはアプリのほかにバックグラウンドサービスを構成するため、誰もデバイスにログインしていない間も保護は動き続けます。

**Mac のデスクトップにユーザーがログインしている状態で初回インストール** を行った場合、インストーラーの終了時にセットアップウィンドウが開きます。それ以外の場合は、次回ログイン時に開くか、`/Applications` から Takumi Agent を起動してください。

### コマンドラインを用いたインストール {#scripted-install}

Takumi Agent のインストールは、コマンドラインからも実行できます。次のようにパッケージをダウンロードし、登録キーを `installer` の環境変数 `TAKUMI_AGENT_ENDPOINT_ENROLLMENT_TOKEN` で渡します。

```sh
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](#enroll) を飛ばし、[ステップ 5](#trust-ca) から表示されます。渡した登録キーが拒否された場合もインストールは完了し、セットアップウィンドウが通常どおり[ステップ 4](#enroll) で登録キーを求めます。

## ステップ 4: 登録キーの入力 {#enroll}

ステップ 2 で発行した登録キーをセットアップウィンドウに貼り付けます。これにより、Mac デバイスが組織のデバイスとして登録されます。

<img src={require("./installation-step4-setup-window.png").default} alt="登録キーを求めるセットアップウィンドウ" width="516" className="zoomable" />

## ステップ 5: デバイス証明書の信頼 {#trust-ca}

macOS が管理者の資格情報を求めます。この操作は、Mac デバイスのデバイス証明書をシステムキーチェーンで信頼させるために必要です。

<img src={require("./installation-step5-trust-prompt.png").default} alt="証明書の信頼を求めるダイアログ" width="296" className="zoomable" />

macOS はこの操作に管理者の直接の承認を求めるため、インストーラーが自動で行うことはできません。この手順が完了するまで、Mac デバイス上では **未保護**、管理コンソール上では **保護なし** と表示され、捕捉対象のインストールは **フェイルクローズ** で失敗します。つまり、対象エコシステムのパッケージはデバイス上にダウンロードできません。

ダイアログを閉じるなどしてセットアップが中断された場合は、次回アプリの起動時に再度ダイアログが表示されます。また、メニューバーにはセットアップを続行するための **「セットアップを完了…」** ボタンが表示されます。

:::warning 管理者でないユーザーの場合
管理者でないユーザーは、この手順を完了できず、デバイスの登録もできません（アプリ上にもその旨が表示されます）。デバイスの管理者が Takumi Agent を開くまで、デバイスは未保護のままです。
:::

## ステップ 6: システム拡張・プロキシ構成・フィルタの承認 {#approve-filter}

続いて、次の 3 つの承認が求められます。3 つとも承認してください。

### システム拡張の許可 {#approve-sysext}

macOS が **システム拡張の許可** を求めます。これは、Takumi Agent がパッケージレジストリへの通信を扱うために必要な許可です。**システム設定を開く** をクリックすると、**ログイン項目と機能拡張** の **ネットワーク機能拡張** の一覧が表示されます。**TakumiAgent** のトグルをオンにし、管理者パスワードを入力してください。

<div style={{display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "flex-start", marginBottom: "1.25rem"}}>
  <figure style={{margin: 0, textAlign: "center"}}>
    <img src={require("./installation-step6-sysext-prompt.png").default} alt="ネットワーク機能拡張の承認を求めるダイアログ" style={{height: 260, width: "auto"}} className="zoomable" />
    <figcaption style={{fontSize: "0.85rem"}}>1. <b>システム設定を開く</b> をクリック</figcaption>
  </figure>
  <figure style={{margin: 0, textAlign: "center"}}>
    <img src={require("./installation-step6-settings-network-extension.png").default} alt="ネットワーク機能拡張の TakumiAgent のスイッチ" style={{height: 260, width: "auto"}} className="zoomable" />
    <figcaption style={{fontSize: "0.85rem"}}>2. <b>TakumiAgent</b> をオンにする</figcaption>
  </figure>
  <figure style={{margin: 0, textAlign: "center"}}>
    <img src={require("./installation-step6-sysext-password.png").default} alt="システム拡張のための管理者パスワードのダイアログ" style={{height: 260, width: "auto"}} className="zoomable" />
    <figcaption style={{fontSize: "0.85rem"}}>3. パスワードを入力</figcaption>
  </figure>
</div>

ダイアログを閉じるなどしてセットアップが中断された場合は、**システム設定 → 一般 → ログイン項目と機能拡張** で **カテゴリ別** を選択し、**ネットワーク機能拡張** の横の ⓘ をクリックすると再開できます。

### プロキシ構成の許可 {#approve-proxy}

次に **「TakumiAgent Would Like to Add Proxy Configurations」** というダイアログが表示されるので、**許可** をクリックしてください。これは、対象エコシステムのパッケージをインストールする際の通信を、Takumi Guard のプロキシ経由にするために必要な操作です。許可するまで、通信は検査されません。

### コンテンツフィルタリングの許可 {#approve-filter-prompt}

最後に、Takumi Agent に **ネットワークコンテンツのフィルタリング** を許可するかどうかを尋ねるダイアログが表示されます。これはエグレスロックのための許可です。エグレスロックは対象レジストリへの直接の接続をブロックし、Takumi Guard を迂回したパッケージのダウンロードを防ぎます。**許可** をクリックしてください。承認しなくても捕捉は動作しますが、承認するまで Mac デバイスには **要対応** と表示されます。

<img src={require("./installation-step6-filter-prompt.png").default} alt="ネットワークコンテンツのフィルタリングを求めるダイアログ" width="296" className="zoomable" />

セットアップウィンドウのチェックリストは、各手順の完了が確認されるたびに更新されます。各項目の意味は次のとおりです。

| チェックリストの項目     | 意味                                                             |
| ------------------------ | ---------------------------------------------------------------- |
| **機能拡張の承認**       | システム拡張が承認されている                                     |
| **ネットワークフィルタ** | ネットワークフィルタが有効化されている                           |
| **インストールの検査**   | バックグラウンドサービスがパッケージのインストールを検査している |

<img src={require("./installation-step6-checklist.png").default} alt="完了したセットアップのチェックリスト" width="516" className="zoomable" />

3 つの項目がすべて完了しているにもかかわらず **「この Mac はまだ保護されていません」** と表示される場合は、[トラブルシューティング](/docs/ja/t/endpoint/references/troubleshooting.md#still-not-protected)を参照してください。

ダイアログを閉じてしまった場合は、**「承認ダイアログを再表示」** または **「システム設定を開く…」** から再度表示できます。ネットワークフィルタがオフになっている場合は **「ネットワークフィルタをオンにする」** ボタンが、コンテンツフィルタの承認を見送った場合はパネルに **「エグレスロックを有効にする…」** が表示されます。

## ステップ 7: メニューバーの確認 {#verify-menubar}

セットアップが完了すると、Mac デバイスのメニューバーに Takumi のパンダのアイコン <img src={require("./installation-step7-menubar-icon.png").default} alt="メニューバーの Takumi のパンダ" width="44" style={{verticalAlign: "middle", borderRadius: 6}} /> が表示され、その隅に状態を示すバッジが付きます。緑の丸は保護中を表します。その他の状態については[デバイスの状態](/docs/ja/t/endpoint/features/states.md)を参照してください。

アイコンをクリックするとパネルが開き、保護の状態と保護対象ごとの詳細が表示されます。**Guard**（展開するとエコシステムごとに表示）、**コンテナ**、**エグレスロック**、**識別情報**、**ヘルス** の 5 行が並び、利用者の操作で解消できる事象には、行ごとに操作用のボタンが表示されます。その下には、エージェントのバージョンと最終チェックイン時刻、**「今すぐチェックイン」** ボタン、[アプリウィンドウ](/docs/ja/t/endpoint/features/app-window.md)を開く **「Takumi Agent を開く」** ボタン、**ヘルプ**、**「ステータスアイコンを終了」**（保護は継続します）があります。

<img src={require("./installation-step7-menubar-panel.png").default} alt="メニューバーのパネル" width="356" className="zoomable" />

パネルの表示言語は、Mac の言語設定（Takumi Agent 向け）に従います（現在は英語と日本語に対応しています）。

## ステップ 8: 管理コンソールでの確認 {#verify-console}

登録が完了したデバイスは、数秒以内に管理コンソール上に表示されます。その後は、約 5 分ごとに最新の状態が報告されます。

左のナビゲーションバーで **Endpoint** を選択すると、**デバイス** タブが表示されます。セットアップが完了したデバイスをクリックし、表示される詳細パネルで **保護中** と表示されていることを確認してください。

実際のパッケージマネージャーでも保護を確認できます。パッケージマネージャーを個別に設定する必要はありません。例として、npm でテスト用パッケージのインストールを試します。

```sh
npm install @panda-guard/test-malicious
```

:::info
セットアップ前に開いたターミナルは、まだデバイス証明書を信頼していません。この確認は、新しいターミナルウィンドウで実行してください。
:::

npm が `403 Forbidden` を返せば、Takumi Guard がリクエストを検査してブロックしています。それ以外の結果になった場合は、メニューバーのパネルを開いて[デバイスの状態](/docs/ja/t/endpoint/features/states.md)を確認してください。

Go modules でも、Guard のテスト用モジュールを使って、パッケージマネージャーの設定を変更せずに保護が有効であることを確認できます。こちらも `403 Forbidden` が返されます。

```sh
cd $(mktemp -d) && go mod init verify-takumi-guard && go get github.com/flatt-security/hola-takumi-go@v0.1.0
```

## セットアップ完了後の追加作業 {#next}

デバイス上のセットアップが完了したら、ターミナル、IDE、AI コーディングエージェントを再起動してください。

また、コンテナなど隔離された環境で開発する場合は、コンテナでデバイス証明書を信頼させる設定が一度だけ必要です。開発環境ごとの設定方法については、[Takumi Agent を使った開発](/docs/ja/t/endpoint/development.md)を参照してください。

## 更新 {#updates}

エージェントは自動で更新されます。詳細については[デバイスの管理](/docs/ja/t/endpoint/features/managing-devices.md#updates)を参照してください。

## アンインストール {#uninstall}

Mac デバイス上で Takumi Agent のアプリを削除するだけでは、システム拡張とネットワーク設定が残ります。アンインストールの手順については[アンインストール](/docs/ja/t/endpoint/features/uninstall.md)を参照してください。