Skip to main content
View as Markdown

Quickstart

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.

Takumi Guard protects your development environment by blocking malicious packages before they reach your machine. It works as a transparent proxy for npm, PyPI, and RubyGems — no code changes required, just a one-time registry configuration.

Choose Your Setup Level​

Takumi Guard offers three levels of access. Pick the one that fits your needs:

LevelWhat You GetRequires
AnonymousMalicious package blockingRegistry URL only
Email-VerifiedBlocking + download tracking + breach notificationsEmail registration (free)
OrganizationEverything above + team-wide visibilityShisho Cloud account + GitHub Actions

Most individual developers should start with email-verified access — it takes under a minute and unlocks breach notifications at no cost.

Token Types​

Takumi Guard offers two types of tokens. Both are configured the same way in your package manager.

TokenPrefixHow to IssueUse Case
Email-Verified Tokentg_anon_Email registrationPersonal development (no Shisho Cloud account needed)
Org User Tokentg_org_Console or Guard APIOrganization-wide installation tracking
Org User Tokens
  • Org user tokens require an active Takumi subscription with Guard enabled. See Pricing & Billing for details.
  • For an example of issuing tokens via the Guard API, see Admin Deployment.

One Token, All Ecosystems​

A single token works across all Takumi Guard ecosystems, regardless of type.

  • npm — npm, pnpm, yarn, bun
  • PyPI — pip, uv, poetry
  • RubyGems — Bundler

Use the same token to configure as many package managers as you need. If you already set up npm and want to add PyPI (or vice versa), you do not need to register again — just configure the additional package manager with the same key.

Already registered?

If you've already registered via npm, PyPI, or RubyGems, you don't need to register again. Use the API key you already have and jump to any of the setup guides below to add another ecosystem.

Ecosystem Setup Guides​

Follow the guide for each ecosystem you want to protect:

npm​

Covers npm, pnpm, yarn, and bun. Includes local development, .npmrc configuration, and GitHub Actions setup.

Set up npm →

PyPI​

Covers pip, uv, and poetry. Includes local development, environment variable configuration, and GitHub Actions setup.

Set up PyPI →

RubyGems​

Covers Bundler. Includes local development and GitHub Actions setup.

Set up RubyGems →

Quick Reference​

Already have your token? Here are the one-line commands for each package manager:

npm ecosystem​

# npm / pnpm
npm config set registry https://npm.flatt.tech/
npm config set //npm.flatt.tech/:_authToken tg_YOUR_TOKEN
# yarn (v2+) — add to .yarnrc.yml
npmRegistryServer: "https://npm.flatt.tech/"
npmAuthToken: "tg_YOUR_TOKEN"
# bun — add to bunfig.toml
[install]
registry = { url = "https://npm.flatt.tech/", token = "tg_YOUR_TOKEN" }

PyPI ecosystem​

# pip (persists to disk)
pip config set global.index-url https://token:tg_YOUR_TOKEN@pypi.flatt.tech/simple/

# uv — add to shell profile (uv does not read pip config)
export UV_INDEX_URL=https://token:tg_YOUR_TOKEN@pypi.flatt.tech/simple/
# poetry
poetry source add --priority=primary takumi-guard https://pypi.flatt.tech/simple/
poetry config http-basic.takumi-guard token tg_YOUR_TOKEN

RubyGems ecosystem​

# Bundler — routes all bundle install calls through Guard
bundle config set --global mirror.https://rubygems.org https://token:tg_YOUR_TOKEN@rubygems.flatt.tech/

Verify Your Setup​

After configuring any package manager, test that Takumi Guard is working by attempting to install a known blocked package:

npm install @panda-guard/test-malicious

If Takumi Guard is configured correctly, the install will fail with a 403 Forbidden error.

Next Steps​

Last updated on