# Admin Deployment {#admin-deployment}

We provide deployment scripts for setting up Takumi Guard across your organization's developer machines using management tools. Customize them to suit your management tool.

:::info Paid Feature
This feature requires an active Takumi subscription with Guard enabled. See [Pricing & Billing](/docs/t/guard/billing/index.md) for details.
:::

## Overview {#overview}

The setup consists of two phases:

1. **Preparation** — Create a bot in Shisho Cloud console and download the setup script
2. **Deployment** — Create a wrapper script for your management tool and push it along with the setup script to target machines

Tokens issued by the setup script can be viewed and managed in the Shisho Cloud console under **Guard** > **Tokens**.

![Token management UI](/docs/_md-assets/6878f477ed-ui-tokens.png)

## Prerequisites {#prerequisites}

Before deploying, complete the following steps in Shisho Cloud console:

1. **Create a bot** — Click the "Add Bot" button on the Settings > Bots page
2. **Assign the role** — Select the "Takumi Guard Token Issuer" role for the bot
3. **Get the API key** — On the bot's detail page, click "Create API Key" and save it securely

:::info
For detailed instructions on creating bots and API keys, see [this guide](/docs/c/accessing-via-shishoctl-cli/index.md#sign-in-with-an-api-key).
:::

## Setup Script {#setup-script}

We provide a setup script that handles token minting and package manager configuration. Download the script for your platform:

- **macOS / Linux:** [https://shisho.dev/releases/takumi-guard-setup-0.1.1.sh](https://shisho.dev/releases/takumi-guard-setup-0.1.1.sh)
- **Windows:** [https://shisho.dev/releases/takumi-guard-setup-0.1.1.ps1](https://shisho.dev/releases/takumi-guard-setup-0.1.1.ps1)

:::info
Target machines must have `curl` installed (macOS and Linux).
:::

### Usage {#usage}

The setup script only modifies config files **for the user who runs it**. To deploy across all users in your organization, use the wrapper scripts described in the [Deployment Examples](#deployment-examples) section.

Run the setup script as follows. Pass the API key via the `TG_BOT_API_KEY` environment variable:

```sh
TG_BOT_API_KEY="shisho_apikey_..." ./setup.sh <BOT_ID> <USER_IDENTIFIER>
```

| Parameter         | Description                             |
| ----------------- | --------------------------------------- |
| `TG_BOT_API_KEY`  | Bot API key (environment variable)      |
| `BOT_ID`          | Bot ID from Shisho Cloud console        |
| `USER_IDENTIFIER` | A unique identifier for the device/user |

To limit which package managers are configured, pass the scope as the third argument.

```sh
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_IDENTIFIER npm,pypi
```

| Scope  | Package managers configured |
| ------ | --------------------------- |
| `npm`  | npm, pnpm, yarn (v2+), bun  |
| `pypi` | pip, uv, poetry             |

### Choosing a USER_IDENTIFIER {#user-identifier}

The `USER_IDENTIFIER` is an opaque string that identifies a device or user. Choose a consistent naming convention for your organization.

**Constraints:**

- Allowed characters: `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
- Length: 4 to 255 characters

Here are some examples of identifiers you can use.

| Example                            | Value                | Description                                 |
| ---------------------------------- | -------------------- | ------------------------------------------- |
| Device serial number + OS username | `C02X1234_jdoe`      | Hardware serial number from the device BIOS |
| Asset management ID + employee ID  | `ASSET0042_EMP12345` | IDs managed by your organization            |
| MDM device ID + OS username        | `a401c7d0_jdoe`      | Device ID assigned by your MDM tool         |

:::warning
Verify that your chosen identifier is unique within your organization. Some identifiers (e.g., serial numbers) may be empty or not unique on certain environments such as custom-built PCs or virtual machines. Use a value that reliably distinguishes each device and user.
:::

### Behavior {#behavior}

- **First run** — The setup script mints a token, creates a timestamped backup of each existing config file (e.g. `~/.npmrc-backup-20260408-162351`), and appends Guard settings. Existing non-Guard settings are not modified.
- **Subsequent runs** — The setup script detects the existing token and reuses it without minting a new one. Config files that already have Guard settings are skipped (no changes, no backups). You can add new scopes incrementally — for example, run with `npm` first, then `pypi` later.
- **Automatic rollback** — If the script fails midway, all config files changed so far are automatically restored to their pre-execution state. No manual intervention is needed.
- **Manual rollback** — The setup script creates a timestamped backup before modifying each config file (e.g. `~/.npmrc-backup-20260408-162351`). To undo Guard settings, copy the backup file back to its original name (e.g. `cp ~/.npmrc-backup-20260408-162351 ~/.npmrc`).

:::note
Tokens are only minted on the first run. Subsequent runs reuse the existing token. Revoke tokens that are no longer needed (e.g., after device replacement or employee departure) from the Shisho Cloud console.
:::

:::warning
If a package manager already has a different registry configured (e.g., a private npm registry), the setup script overwrites the existing registry with the Guard registry. A timestamped backup is created before each overwrite, but we recommend reviewing registry settings on target machines before deployment.
:::

## Deployment Examples {#deployment-examples}

The deployment method varies depending on your management tool and target OS. Below are common deployment patterns for each platform.

### macOS / Linux {#wrapper-macos-linux}

Management tools typically execute scripts with root privileges. To deploy across all developers, use a wrapper script that switches to each user's context as shown below.

:::note
To also configure Guard for the root user, run the setup script once without switching users inside the wrapper script.
:::

#### macOS {#wrapper-macos}

```sh
#!/bin/bash
# deploy-guard.sh — Admin deployment wrapper

# TODO: Replace with your Bot ID and API key from Shisho Cloud console
BOT_ID="BTXXXXXXXXXXXXXXXXXXXXXXXXXX"
export TG_BOT_API_KEY="shisho_apikey_XXXXX"

# Download the setup script
# Replace {VERSION} with the actual version number
curl -sL -o /tmp/takumi-guard-setup.sh https://shisho.dev/releases/takumi-guard-setup-{VERSION}.sh
chmod 755 /tmp/takumi-guard-setup.sh

# Get the device serial number for USER_IDENTIFIER generation
SERIAL=$(ioreg -l | grep IOPlatformSerialNumber | awk -F'"' '{print $4}')

# Run the setup script for each user on this machine
for USER_HOME in /Users/*; do
  USER_NAME=$(basename "$USER_HOME")

  # Skip system directories and non-existent paths
  [ "$USER_NAME" = "Shared" ] && continue
  [ ! -d "$USER_HOME" ] && continue

  # Skip if the user account does not exist
  id "$USER_NAME" >/dev/null 2>&1 || continue

  # Build a unique identifier for this device + user combination
  USER_IDENTIFIER="${SERIAL}_${USER_NAME}"

  # Run the setup script as this user (login shell for PATH resolution)
  sudo -u "$USER_NAME" -i -H env TG_BOT_API_KEY="$TG_BOT_API_KEY" \
    /tmp/takumi-guard-setup.sh "$BOT_ID" "$USER_IDENTIFIER"

  echo "[Done] $USER_NAME (USER_IDENTIFIER: $USER_IDENTIFIER)"
done

# Clean up credentials and temporary files
unset TG_BOT_API_KEY
rm -f /tmp/takumi-guard-setup.sh
```

#### Linux {#wrapper-linux}

```bash
#!/bin/bash
# deploy-guard.sh — Admin deployment wrapper

# TODO: Replace with your Bot ID and API key from Shisho Cloud console
BOT_ID="BTXXXXXXXXXXXXXXXXXXXXXXXXXX"
export TG_BOT_API_KEY="shisho_apikey_XXXXX"

# Download the setup script
# Replace {VERSION} with the actual version number
curl -sL -o /tmp/takumi-guard-setup.sh https://shisho.dev/releases/takumi-guard-setup-{VERSION}.sh
chmod 755 /tmp/takumi-guard-setup.sh

# Get the device serial number for USER_IDENTIFIER generation
SERIAL=$(dmidecode -s system-serial-number)

# Run the setup script for each user on this machine
for USER_HOME in /home/*; do
  USER_NAME=$(basename "$USER_HOME")

  # Skip non-existent paths
  [ ! -d "$USER_HOME" ] && continue

  # Skip if the user account does not exist
  id "$USER_NAME" >/dev/null 2>&1 || continue

  # Build a unique identifier for this device + user combination
  USER_IDENTIFIER="${SERIAL}_${USER_NAME}"

  # Run the setup script as this user (login shell for PATH resolution)
  sudo -u "$USER_NAME" -i -H env TG_BOT_API_KEY="$TG_BOT_API_KEY" \
    /tmp/takumi-guard-setup.sh "$BOT_ID" "$USER_IDENTIFIER"

  echo "[Done] $USER_NAME (USER_IDENTIFIER: $USER_IDENTIFIER)"
done

# Clean up credentials and temporary files
unset TG_BOT_API_KEY
rm -f /tmp/takumi-guard-setup.sh
```

### Windows {#deployment-windows}

Distribute the script via your management tool and run the setup script directly under the logged-in user's privileges.

## Security Considerations {#security}

- **API key handling** — If the bot API key is compromised, immediately revoke it from the Shisho Cloud console. Previously minted tokens are not affected.
- **Key rotation** — After deploying to all target machines, rotate the bot API key in Shisho Cloud console as a preventive measure.
- **Token revocation** — If a token is compromised, revoke it from the Shisho Cloud console. Revocation takes effect within a maximum of 60 seconds.