AgentPM™

install#

Resolve and download tools declared in an agent manifest and make them runnable from your app.

Overview#

agentpm install reads your agent.json (kind=agent), resolves the tool versions, downloads artifacts, and prepares them for execution in managed subprocesses.

Command synopsis#

agentpm install [<spec>] [--manifest <path>] [--frozen] [--refresh] [--update-range] [--require_attestation] [--quiet] [--token <PAT>]

Arguments#

  • spec (optional). Install a specific tool by spec, e.g. @namespace/name@0.1.2 or @namespace/name@^1.2. Adds/updates the entry in agent.json → tools[] and installs it.
  • --manifest <path> (default: agent.json). Path to the agent manifest to read/write.
  • --frozen. Fail if anything would change the resolved set (no re-resolution or lock updates).
  • --refresh. Force re-resolution and re-download even if everything looks satisfied locally (bypass caches).
  • --update-range. If spec conflicts with the current range in agent.json, update the range in the manifest to match the requested spec.
  • --require_attestation — Fail install if any resolved artifact is missing a registry attestation signature (supply-chain enforcement).
  • --quiet. Reduce output noise (spinner/logs).
  • --token <PAT> (env: AGENTPM_TOKEN). Personal Access Token for headless auth (overrides env/file).
Scope

agentpm install currently supports kind: "agent" manifests only. Running it on a kind: "tool" manifest will error.

Token resolution order

flag (--token) > env (AGENTPM_TOKEN) > token file (written by agentpm login).

Examples#

Install all tools declared in the manifest#

agentpm install

Sample output:

• Reading credentials…
✓ Reading credentials (0ms)
• Resolving versions…
✓ Resolving versions (10ms)
• Requesting download URLs…
✓ Requesting download URLs (50ms)
• Downloading tools…
✓ Downloading tools (1ms)
• Finalizing install…
✓ Finalizing install (10ms)
Installed ✓

Add + install a specific tool by spec#

agentpm install @zack/summarize@0.1.2
# writes/updates the entry in agent.json → tools[] and installs the artifact

Re-resolve and re-download everything#

agentpm install --refresh

Prevent any changes to the resolved set#

agentpm install --frozen
# exits with an error if resolution would change

Update the manifest’s version range to match your spec#

agentpm install @zack/summarize@0.1.2 --update-range

What install does#

  1. Reads credentials and your agent.json.
  2. Resolves versions (respecting exact pins or semver ranges).
  3. Fetches download URLs and downloads artifacts.
  4. Writes updates when installing via spec (adds/updates in tools[]).

Install locations

  • Prepared tools: .agentpm/tools/<namespace>/<name>/<version>
  • Download cache (tgz artifacts): .agentpm/cache (used unless you pass --refresh)

Lockfile (agent.lock)#

agentpm install writes a lockfile at the project root to guarantee repeatable installs across machines and CI.

Example:

{
  "dependencies": {
    "@zack/summarize": {
      "integrity": "dd58…ae6d",
      "version": "0.1.2"
    }
  },
  "generated": "2025-09-27T00:09:28.488662Z",
  "lockfile_version": 1
}

What’s in it

  • dependencies — the exact versions resolved for each tool.
  • integrity — a cryptographic checksum of the artifact used to verify content.
  • generated — timestamp for traceability.
  • lockfile_version — format version (may evolve over time).

How it’s used

  • On install, the lockfile pins versions and checksums.
  • --frozen will fail if the resolved set would change (protects CI from drift).
  • --refresh re-resolves and re-downloads; if versions change (e.g., semver ranges), the lockfile is updated accordingly.

Best practices

  • Commit agent.lock to version control.
  • Don’t edit it by hand—change agent.json (or pass a spec) and re-run agentpm install.
  • Use exact pins for production; if using ranges, combine with --frozen in CI.

Verify registry attestation on install#

Ensure every artifact you pull has a registry attestation:

agentpm install --require_attestation
  • Fails the install if any resolved artifact lacks the registry’s attested signature.
  • Works alongside your normal resolution/lockfile flow.
  • Use in CI and production to prevent un-attested packages from entering your environment.

Common flows#

  • Declared in manifest → install all
# agent.json already has tools[] entries
agentpm install
  • Ad-hoc add a tool
agentpm install @namespace/my-tool@0.3.1
# now present in tools[] and installed
  • Pin vs range
    • Use exact pins (0.1.2) for reproducibility.

Verify your install#

# Check that artifacts exist
ls -R .agentpm/tools
 
# Optional: run your host app and call the tool;
# tools execute in managed subprocesses, isolated from host deps.

Errors & troubleshooting#

  • “supports kind=agent only.”. You ran install in a kind: "tool" project. Use agentpm init --kind agent … for agents, and declare tools there.
  • Frozen mismatch. If --frozen fails, you’re attempting to change the resolved set. Remove --frozen or commit the intended updates first.
  • Stale cache. If you suspect a bad/corrupt artifact or want to force re-fetch, use --refresh.
  1. Declare tools in agent.json → tools[] or install via agentpm install @namespace/name@version.
  2. Run agentpm install locally; commit manifest changes.
  3. In CI, run:
agentpm lint --strict
agentpm install --frozen --quiet
←CLIlogin
→CLIpublish