Admin Deployment

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

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.

Paid Feature

This feature requires an active Takumi subscription with Guard enabled. See Pricing & Billing for details.

Overview

The setup consists of two phases:

Preparation — Create a bot in Shisho Cloud console and download the setup script
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

Prerequisites

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

Create a bot — Click the "Add Bot" button on the Settings > Bots page
Assign the role — Select the "Takumi Guard Token Issuer" role for the bot
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.

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
Windows: https://shisho.dev/releases/takumi-guard-setup-0.1.1.ps1

info

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

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 section.

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

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.

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

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

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

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

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

#!/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

#!/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

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

Security Considerations

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.

Overview​

Prerequisites​

Setup Script​

Usage​

Choosing a USER_IDENTIFIER​

Behavior​

Deployment Examples​

macOS / Linux​

macOS​

Linux​

Windows​

Security Considerations​

Overview

Prerequisites

Setup Script

Usage

Choosing a USER_IDENTIFIER

Behavior

Deployment Examples

macOS / Linux

macOS

Linux

Windows

Security Considerations