---
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, auditing, or dependency installation for an apm
  package -> `apm-workflow`.
metadata:
  version: "1.0.0"
  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.