---
name: apm-install
description: >
  Use when installing, pinning, or upgrading the apm (Agent Package Manager)
  CLI itself, or installing and managing an agent runtime apm drives. Not
  authoring, publishing, or auditing apm packages -> `apm-workflow`.
metadata:
  category: apm
  source_keys:
    - context7-microsoft-apm
---

## Gotchas

- apm never executes an agent itself — it only installs and manages the runtimes that do. Installing apm alone leaves the user with a package manager and no working agent CLI, so Step 2 is required whenever the user actually wants one; skip it only when they explicitly want the package manager alone.
- `apm runtime setup copilot` needs Node.js v22+ and npm v10+ already on `PATH`; apm will not install them for you.

## Step 1 — Install the apm CLI

If `apm --version` already answers and the user is not pinning or upgrading, skip to Step 2.

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: `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: `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
- **Air-gapped mirror / GitHub Enterprise** — an air-gapped host cannot reach `aka.ms` at all, so get `install.sh` onto the box and run it from disk instead of piping. Point it at the mirror with `APM_RELEASE_BASE_URL` and pin `VERSION`: `APM_RELEASE_BASE_URL=https://mirror.corp/apm VERSION=v1.2.3 sh install.sh`; add `APM_RELEASE_METADATA_URL` instead if you leave `VERSION` unset. `GITHUB_URL` is the GitHub Enterprise host, not a release mirror. All four are ordinary environment variables that also work through the pipe — running from disk is a network constraint, not a script one.
- **pip** — `pip install apm-cli` requires Python 3.10+. Not on an externally-managed (PEP 668) Python such as Debian or Ubuntu, where it hard-fails with `error: externally-managed-environment`; use pipx below. The quick-install script has no Python prerequisite, so prefer it unless the environment is pip-first.
- **pipx** — `pipx install apm-cli` on those PEP 668 environments. Same PyPI package, but pipx builds an isolated venv and exposes `apm` on `PATH`.
- **Manual** — download the platform archive from the GitHub releases page, extract, and place the binary on `PATH`.

Verify with `apm --version`.

## Step 2 — 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.