AgentPM™

install#

Install tools or agents, resolve tool dependencies, and make the resulting packages available to your app.

Overview#

agentpm install supports two workflows:

  • manifest-driven install from a local kind: "agent" manifest
  • direct package install for either a tool spec or an agent spec

In both cases, AgentPM resolves package versions, downloads artifacts, installs them into the normalized .agentpm layout, and writes agent.lock.

Command synopsis#

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

Arguments#

  • spec (optional). Install a specific package by spec, e.g. @namespace/name@0.1.2 or @namespace/name@^1.2.
    • If it resolves to a tool, AgentPM installs the tool directly.
    • If it resolves to an agent, AgentPM installs the agent artifact and then resolves/installs its tool dependencies.
    • In a local kind: "agent" project, direct tool installs still add/update the entry in agent.json → tools[].
  • --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

Tools are the only resolved dependency type today. skills, knowledge, memory, and profiles are preserved in manifest/lock metadata but are not resolved or installed.

Token resolution order

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

Examples#

Install all tools declared in a local agent manifest#

agentpm install

Sample output:

• Reading credentials…
✓ Reading credentials (0ms)
• Resolving versions…
✓ Resolving versions (10ms)
• Requesting download URLs…
✓ Requesting download URLs (50ms)
• Downloading packages…
✓ Downloading packages (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

Install a published agent package directly#

agentpm install @zack/support-agent@0.1.0

This installs:

  • the agent artifact under .agentpm/agents/zack/support-agent/0.1.0/
  • the agent's resolved tool dependencies under .agentpm/tools/...

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, for manifest-driven installs, your local agent.json.
  2. Resolves package versions (respecting exact pins or semver ranges).
  3. Fetches download URLs and downloads artifacts.
  4. Chooses install directories by kind:
    • tools → .agentpm/tools/...
    • agents → .agentpm/agents/...
  5. Writes updates when installing a direct tool spec in a local agent project (adds/updates tools[]).

Install locations

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

Lockfile (agent.lock)#

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

Example:

{
  "lockfile_version": 2,
  "packages": {
    "tool:@zack/summarize@0.1.2": {
      "kind": "tool",
      "name": "@zack/summarize",
      "version": "0.1.2",
      "integrity": "dd58…ae6d"
    }
  },
  "roots": {
    "local:agent": {
      "name": "research-assistant",
      "version": "0.1.0",
      "tools": ["tool:@zack/summarize@0.1.2"],
      "reserved": {
        "skills": [],
        "knowledge": [],
        "memory": [],
        "profiles": []
      }
    }
  }
}

What’s in it

  • packages — exact package identities and integrities.
  • roots — local manifest roots and installed registry-agent roots.
  • integrity — a cryptographic checksum of the artifact used to verify content.
  • generated — timestamp for traceability.
  • lockfile_version — the current format version.

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.
  • Existing tool-only v1 lockfiles are still read where practical, but normal installs now write v2.

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.

Manifest-driven vs direct package install#

agentpm install supports two install sources:

  • Manifest-driven install

    • Run agentpm install in a project with a local kind: "agent" manifest.
    • AgentPM reads the local agent.json, resolves the tools declared there, and installs those tools into .agentpm/tools/....
    • agent.lock records the local manifest as a local:agent root.

  • Direct package install

    • Run agentpm install @namespace/name@version.
    • If that package resolves to a tool, AgentPM installs the tool directly into .agentpm/tools/....
    • If that package resolves to an agent, AgentPM installs the agent package into .agentpm/agents/..., then resolves and installs its tools into .agentpm/tools/....
    • agent.lock records installed registry agents with roots like agent:@namespace/name@version.

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.

Errors & troubleshooting#

  • Reserved field warnings under --strict. If your agent manifest populates skills, knowledge, memory, or profiles, lint will warn that those fields are validated and preserved but not resolved today. Leave them empty unless you intentionally want to track future references now.
  • Unsupported v1 agent graph under --frozen. If a legacy v1 lockfile cannot represent the requested agent dependency graph, rerun agentpm install without --frozen to regenerate agent.lock v2.
  • 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 and agent.lock changes.
  3. In CI, run:
agentpm lint --strict
agentpm install --frozen --quiet
←CLIlogin
→CLIpublish