---
name: apm-install
description: >
  Use when the user wants to install the apm (Agent Package Manager) CLI
  itself, pin or upgrade its version, set up an air-gapped/enterprise mirror
  install, or install and manage an agent runtime that apm drives (Copilot
  CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to
  a version", "apm runtime setup", "which runtime will apm run pick". Do not
  use for authoring apm.yml, scaffolding a package/marketplace, compiling,
  packing, publishing, or running apm audit — use apm-workflow for those.
metadata:
  category: apm
  source_keys:
    - context7-microsoft-apm
---

## Gotchas

- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager.
- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form.
- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first.
- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you.

## Install apm

Default:

```bash
curl -sSL https://aka.ms/apm-unix | sh
```

Escape hatches — combine as needed:
- Pin a version: append `@vX.Y.Z` to the piped script's arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
- Custom install directory: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
- pip (Python 3.10+ environments): `pip install apm-cli`.
- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.

Verify with `apm --version`.

## Install or manage an agent runtime

Default:

```bash
apm runtime setup copilot
```

Other targets: `apm runtime setup codex`, `apm runtime setup gemini`, `apm runtime setup llm`.

- `apm runtime list` — show installed runtimes.
- `apm runtime status` — show which runtime `apm run` will pick by default.
- `apm runtime remove <name> -y` — uninstall without an interactive prompt.