# Takumi Guard の複数端末一括導入が容易に

Takumi Guard に**管理ツールによる一括セットアップ機能**が追加されました。既存の管理ツールを使って、開発者の操作なしに組織全体の端末に Guard を展開できます。

## 概要

大規模なチームでは、個々の開発者マシンに Takumi Guard をセットアップするのに時間がかかります。一括セットアップ機能は、npm・pip・uv・Poetry に対して Guard レジストリプロキシを設定するスクリプトを提供し、トークンの発行とクレデンシャルの設定を自動的に処理します。

セットアップスクリプトによって発行されたトークンは、Takumi / Shisho Cloud コンソールの **Guard** > **トークン** で一覧・管理できます。

![トークン管理画面](/docs/ja/_md-assets/602b77b9be-ui-tokens.png)

## 利用方法

以下の図は、一括セットアップの全体構成を示しています。

```mermaid
flowchart LR
    subgraph AdminSide[管理者 / 管理ツール MDM等]
        Admin[管理者]
        MDM[配信ツール]
    end

    subgraph Cloud[Takumi / Shisho Cloud 管理画面]
        Console[コンソール]
        API[Guard API]
    end

    Dev1[開発者端末 A]
    Dev2[開発者端末 B]:::faded
    Dev3[開発者端末 ...]:::faded
    Proxy[Guard レジストリプロキシ]

    Admin -- Bot 作成と管理用 API キー取得 --> Console
    Admin -- スクリプト登録（管理用APIキー含） --> MDM
    MDM -- セットアップスクリプト実行 --> Dev1
    MDM -.-> Dev2
    MDM -.-> Dev3
    Dev1 & Dev2 & Dev3 -- レジストリ用の個別トークン発行 --> API
    Dev1 & Dev2 & Dev3 -- パッケージ取得 --> Proxy

    classDef faded opacity:0.4
```

手順は以下の通りです。

1. Takumi / Shisho Cloud コンソール（**設定** > **ボット**）で Bot を作成し、「Takumi Guard トークン発行者」ロールを付与する
2. Bot の API キーを生成する
3. **Guard** > **設定** からセットアップスクリプトをダウンロードする
4. お使いの管理ツール（Jamf、Intune、Ansible など）でラッパースクリプトを作成し、対象端末に配信する

詳しい手順は[管理ツールによる一括セットアップ](/docs/ja/t/guard/features/admin-deployment)ガイドを参照してください。

:::info 有料機能
この機能を利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing)を参照してください。
:::

## 主な特徴

### マルチエコシステム対応

npm・pip・uv・Poetry を 1 回のスクリプト実行でまとめて設定できます。開発者がどのパッケージマネージャーを使っていても、個別に手順を用意する必要はありません。

### 冪等な実行

同じスクリプトを複数回実行しても安全です。初回実行時にトークンを発行し、設定ファイルを更新しますが、再実行時には既存のトークンを検出して再利用し、設定済みのツールはスキップします。管理ツールから定期的に配信しても問題ありません。

### 段階的なスコープ追加

最初は npm のみを対象にセットアップし、後から PyPI を追加するといった段階的な導入が可能です。追加時にも既存の設定は維持されます。

```sh
# 初回：npm のみセットアップ
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_ID npm

# 後日：PyPI を追加（npm の設定はそのまま維持）
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_ID pypi
```

### バックアップ作成

設定ファイルを変更する前に、タイムスタンプ付きの永続バックアップを自動的に作成します（例：`~/.npmrc-backup-20260408-162351`）。万が一 Guard の設定を元に戻したい場合は、バックアップファイルをコピーするだけで復旧できます。

## 留意事項

メール認証トークン（`tg_anon_…`）で既に Guard を利用しているユーザーを、組織ユーザートークン（`tg_org_…`）にまとめることはできません。メール認証トークンと組織ユーザートークンは独立した認証方式であり、既存のメール認証トークンは引き続きそのまま利用できますが、一括セットアップで発行される組織ユーザートークンとは別のものです。

組織全体で統一した管理を行いたい場合は、一括セットアップで新たに組織ユーザートークンを配信し、開発者に既存のメール認証トークンの設定を削除してもらうことを推奨します。

## 組織での利用を始める

Takumi Guard の組織向け機能（一括セットアップ、インストールログの検索など）を利用するには、Takumi サブスクリプションの契約と Guard の有効化が必要です。

1. [https://cloud.shisho.dev/hello/takumi](https://cloud.shisho.dev/hello/takumi) にアクセスし、サインインする
2. 組織を登録し、Takumi サブスクリプションを契約する
3. 画面左のサイドバーから **Guard** > **設定** にアクセスする
4. 「有効化する」ボタンをクリックして Guard を有効化する

![Guard 設定画面](/docs/ja/_md-assets/28f3d7169a-ui-guard-settings.png)

有効化が完了したら、[管理ツールによる一括セットアップ](/docs/ja/t/guard/features/admin-deployment)ガイドに従ってセットアップを進めてください。