--- title: Getting Started with Tank description: Install the Tank CLI, authenticate with GitHub, and install your first AI agent skill in under 5 minutes — with SHA-512 integrity verification and permission budgets. --- # 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 the stable version with npm: ```bash npm install -g @tankpkg/cli ``` For nightly builds (latest features, may be unstable): ```bash npm install -g @tankpkg/cli@nightly ``` ### Homebrew (macOS) ```bash brew install tankpkg/tap/tank ``` Verify the installation succeeded: ```bash 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. By default, the CLI connects to the public registry at `https://www.tankpkg.dev`. Your token is stored locally in `~/.tank/config.json` — it never leaves your machine unless you're making authenticated API calls. ```bash tank login ``` ### Connecting to a Different Registry By default, the CLI connects to `www.tankpkg.dev`. To use a self-hosted or nightly registry: ```bash # Self-hosted tank login --registry https://tank.yourcompany.com # Nightly TANK_REGISTRY_URL=https://nightly.tankpkg.dev tank search hello ``` If you are using a self-hosted instance, specify your registry URL: ```bash tank login --registry https://tank.yourcompany.com ``` 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: ```bash 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: ```bash tank install @org/skill-name ``` To install a specific version range: ```bash tank install @org/skill-name '^1.2.0' ``` For a global install (available to all your agents, stored in `~/.tank/skills/`): ```bash 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: ```bash # 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: ```bash 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: ```bash # Validate the skill without uploading anything tank doctor tank publish --dry-run # Publish to the registry tank publish ``` See the [Publishing guide](/docs/publishing) 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: ```bash 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](/docs/installing)** — version ranges, lockfiles, dependency resolution, and security filters during extraction - **[Publishing Skills](/docs/publishing)** — the full publish workflow, permission escalation rules, and what the 6-stage scanner checks - **[CLI Reference](/docs/cli)** — every Tank command with all flags and examples - **[Security Model](/docs/security)** — how the 6-stage scanning pipeline works and what it catches - **[Permissions](/docs/permissions)** — the full permission type reference and how budgets are enforced