Getting Started with Tank

Tank is a security-first package manager for AI agent skills. Every install is SHA-512 verified, every skill is statically analyzed before it reaches the registry, and permission budgets prevent skills from accessing more than they declare. This guide takes you from zero to a fully verified working setup.

Prerequisites

Before installing Tank, confirm you have:

Requirement	Minimum Version	Check
Node.js	24+	node --version
npm	any	npm --version
GitHub account	—	Required for tank login

Step 1 — Install the CLI

Install with npm:

npm install -g @tankpkg/cli

Homebrew (macOS)

brew install tankpkg/tap/tank

Verify the installation succeeded:

tank --version

You should see a version string like tank/0.x.y. If you get a "command not found" error, ensure your global bin directory is on your PATH.

Step 2 — Authenticate

Tank uses GitHub OAuth for authentication. Your token is stored locally in ~/.tank/config.json — it never leaves your machine unless you're making authenticated API calls.

tank login

This opens your browser for the GitHub OAuth flow. After authorizing, the CLI polls for the token exchange and confirms authentication.

Verify your identity afterwards:

tank whoami

Expected output:

Logged in as: your-github-username
Token: tank_••••••••••••••••

Step 3 — Install Your First Skill

Install a skill from the registry using its scoped package name:

tank install @org/skill-name

To install a specific version range:

tank install @org/skill-name '^1.2.0'

For a global install (available to all your agents, stored in ~/.tank/skills/):

tank install @org/skill-name '*' -g

For a local project install (stored in .tank/skills/ relative to your working directory), omit the -g flag. Tank writes the resolved version and SHA-512 integrity hash to tank.lock — making future installs fully deterministic.

Step 4 — Verify Safety and Integrity

After installing, run the verification suite:

# Confirm every installed file matches its lockfile hash
tank verify

# Display the resolved permission summary for all installed skills
tank permissions

# Show the security scan results for a specific skill
tank audit @org/skill-name

tank permissions aggregates all declared permissions across your installed skills and shows you what your agent is allowed to do. If any skill claims permissions outside your project's permission budget (defined in tank.json), installation will have already failed — but auditing afterward confirms the resolved state.

`tank verify` recomputes SHA-512 hashes of all installed files and compares them against `tank.lock`. A failed verify means files were modified on disk after install — treat this as a security event.

Step 5 — Create Your First Skill (Publisher Path)

If you want to publish your own skill rather than just consume them, start here:

mkdir my-skill && cd my-skill
tank init

tank init runs an interactive prompt that generates a valid tank.json manifest with your skill's name, version, description, and permission declarations.

Once your skill is ready, publish it safely:

# Validate the skill without uploading anything
tank doctor
tank publish --dry-run

# Publish to the registry
tank publish

See the Publishing guide for the full publish workflow, permission escalation rules, and what the security scanner checks.

Success Criteria Checklist

You are ready to use Tank in production when all of the following are true:

• tank --version prints a version string
• tank whoami shows your GitHub username and a valid token
• tank install @org/skill-name completes without integrity errors
• tank verify exits with code 0
• tank permissions shows only the permissions you expect
• tank audit @org/skill-name shows no critical or high findings

Troubleshooting

tank login opens the browser but never completes

The CLI polls the exchange endpoint for up to 5 minutes. If it times out:

1. Check that https://tankpkg.dev is reachable from your network.
2. Try behind a VPN or different network — corporate proxies sometimes block the OAuth callback.
3. Re-run tank login and complete the flow within 5 minutes.

Commands fail after successful login

Run the self-diagnostic:

tank doctor
tank whoami

tank doctor checks your config file, token validity, registry connectivity, and Node.js version. It prints actionable errors for each check that fails.

Install fails on integrity check

An integrity failure during tank install means the downloaded tarball's SHA-512 hash does not match the value in the registry. This is a hard failure by design — Tank will not install a package it cannot verify.

Steps:

1. Check your network for a proxy or intercepting firewall that might be modifying responses.
2. Retry on a different network.
3. Do not attempt to bypass integrity verification — it is your primary defense against supply chain attacks.

tank permissions output looks too broad

If the permission summary includes access you did not expect:

1. Run tank info @org/skill-name to inspect the declared permissions for that skill.
2. Check if the skill's declared permissions match what the security scanner extracted.
3. Consider removing the skill and selecting an alternative with narrower, more explicit permission scopes.

Command not found after install

Ensure your global npm bin directory is on your PATH. Run npm bin -g to find the directory, then add it to your shell profile.

Next Steps

• Installing Skills — version ranges, lockfiles, dependency resolution, and security filters during extraction
• Publishing Skills — the full publish workflow, permission escalation rules, and what the 6-stage scanner checks
• CLI Reference — every Tank command with all flags and examples
• Security Model — how the 6-stage scanning pipeline works and what it catches
• Permissions — the full permission type reference and how budgets are enforced