# Install AgentX — instructions for AI assistants

You are helping a person install AgentX. AgentX runs on a computer the person
controls. It runs their coding agents
(Claude Code, Codex, Grok CLI) and connects them to their AgentX account at
https://www.agentxhq.com. Your job ends when you hand the person a **claim link**.

If AgentX is already installed on this computer and the person asked you to
upgrade it, do Step 0, then follow **Upgrade an installed AgentX** at the end of
this guide instead of Steps 1–5. An upgrade ends with a version check, not a
claim link.

Follow the steps in order. Talk to the person in plain language, in their own language: the one they write to you in.

## Rules

- Ask before running anything with `sudo`, and say what it does.
- If a step fails, stop and show the exact error. Don't guess around it.
- Never ask for or handle the person's passwords or API keys. They log in
  themselves.
- If the person needs help from a human, AgentX support is on Discord:
  https://discord.gg/C4aPUKmE2b

## Step 0 — Where do your commands run?

AgentX must be installed on the person's own computer or server. First work out
where you are:

- **You run commands on the person's computer or server** (for example Claude
  Code, Codex or Grok CLI running there): continue to Step 1.
- **You can't run commands at all** (a chat assistant in a browser, such as
  ChatGPT.com, claude.ai or Gemini), **or your commands only run in your own
  sandbox or hosted workspace** (for example an agent or work mode in ChatGPT,
  claude.ai or Gemini, or a cloud coding agent): **don't install AgentX there.**
  It would run on a machine the person doesn't control, and the claim link would
  add that machine to their account instead of theirs. If you're not sure where
  your commands run, ask the person.

In the second case, tell the person plainly: "I can't install this on your
computer from here. The easiest way is to put a coding agent on your computer and
let it do the install. I'll help you with that." Then:

1. Help them install one coding agent on their own computer, using its official
   install instructions: Claude Code, Codex, Grok CLI, Gemini CLI, or the one your
   supplier recommends. Any coding agent that runs commands can do the install.
   Claude Code, Codex and Grok CLI can also run their AgentX agents afterwards;
   Gemini CLI can't. See https://www.agentxhq.com/supported-agents.
2. Wait until it runs and they have logged in to it themselves.
3. Give them this prompt to paste into it. Keep the prompt exactly as it is here,
   in English, even if you talk to them in another language:

   ```
   Help me install AgentX on my own computer or server.
   Read https://www.agentxhq.com/install.md and follow it.
   When you're done, give me my claim link.
   ```

4. Stop there. The coding agent does the install and gives them the claim link.

If the person doesn't want to install a coding agent, walk them through the steps
below yourself, one at a time: give one command, wait for them to paste the
output, check it, then give the next. Don't pretend to run anything, and never
install anything in your own sandbox.

## Step 1 — Where should AgentX run?

Ask the person:

> Should AgentX run on the computer you're using right now, or on a remote server (a VPS)?

- **The computer you're using right now:** continue here.
- **A VPS:** ask for the SSH details (host, user, how they log in). Run the rest
  of these steps on the VPS over SSH. On a VPS, use a normal (non-root) login user
  for the agent CLIs.

## Step 2 — Work out the install method

Check the operating system, distribution and CPU architecture
(e.g. `uname -a`, `cat /etc/os-release`, `sw_vers` on Mac, `$env:PROCESSOR_ARCHITECTURE` in PowerShell on Windows, which must print `AMD64`).

| Machine | Method |
|---|---|
| macOS (Apple Silicon or Intel) | Homebrew if it's already installed, otherwise the package without Homebrew (Step 4) |
| Debian / Ubuntu | `.deb` package |
| Arch | `.pkg.tar.zst` package |
| RHEL / Rocky / Alma | `.rpm` package |
| Windows 10 / 11 (x64) | Installer (`.msi`), Desktop or Server, see below (Step 4). Docker Desktop (WSL 2) is the alternative: https://www.agentxhq.com/install/docker |

Use the native package in Step 4 first. Docker is the alternative. The published image is linux/amd64 only. On a Mac or on Windows, pull and run it with `--platform linux/amd64`. Apple Silicon runs that platform by emulation. That emulation is best effort and does not always work. On Linux arm64, `docker pull --platform linux/arm64 agentxhq/agentx-daemon:latest` fails because there is no linux/arm64 image.

On Linux, pick **one** flavor. They conflict, so never install both:

- **Desktop** (`agentx-desktop`): the person's own workstation. Runs as their
  login user. Choose this for a personal computer.
- **Server** (`agentx-server`): an always-on headless host, such as a VPS. Runs as
  root so it can run agents as several users.

On Windows, pick **one** installer:

- **Desktop** (`agentx-desktop_<version>_amd64.msi`): the computer the person signs
  in to. It installs for them alone, needs no administrator, and runs AgentX as
  them while they are signed in. Their agents use their own Claude and other CLI
  logins. Choose this for a personal computer.
- **Server** (`agentx-server_<version>_amd64.msi`): a computer that is always on.
  It installs for the whole computer from PowerShell as administrator, runs AgentX
  as a Windows service that keeps running when nobody is signed in, and runs each
  agent as its own Windows user.

Tell the person which method and flavor you picked, and why, before continuing.

## Step 3 — Make sure a supported agent CLI is installed

The supported agent CLIs are listed at https://www.agentxhq.com/supported-agents.

1. Check which of them are already installed and logged in for the user the
   agents will run as.
2. If at least one is ready, continue.
3. If none is, ask which one the person uses or pays for, and install it with its
   official instructions (linked on that page) **only after they agree**.
4. The person logs in to the CLI themselves. Tell them exactly what to run.

Don't finish until at least one supported CLI is installed and logged in.

## Step 4 — Install AgentX

### macOS

The Mac install (Homebrew, or the package without Homebrew) runs AgentX as the logged-in user, and the agents run as that same user. That install does not run agents as other accounts.

If Homebrew is installed (`brew --version` works), use it:

```sh
brew install agentxhq/tap/agentx
agentx-daemon background
agentx-daemon status
```

To start it at login instead: `brew services start agentx`.

If Homebrew isn't installed, don't install it just for AgentX. Use the package below that matches the Mac: `uname -m` prints `arm64` on Apple Silicon and `x86_64` on Intel. If none of the packages below matches, tell the person and stop. Don't use a package built for a different architecture.

1. Download the package and check its checksum with the first two commands for that Mac. Only continue if the check prints `<filename>: OK`. If it doesn't, the download is corrupt or isn't the file AgentX published, so don't install it.
2. Unpack it and install it with the third command. `./install.sh --launchd` puts `agentx-daemon` and `agentx` in `~/.local/bin` (no sudo) and starts AgentX now and at every login.
3. If the person downloaded the package in a browser instead, run `xattr -dr com.apple.quarantine .` in the unpacked folder before step 2.

#### Mac, Apple Silicon (arm64): `agentx-0.195.1-darwin-arm64.tar.gz`

- Download: https://app.agentxhq.io/releases/agentx-0.195.1-darwin-arm64.tar.gz
- SHA256: `1f1d53b6db453d4e2be60b0aa83022c93edc04ab45c9444aea1c3e668b2858ec`

```sh
curl -fLO https://app.agentxhq.io/releases/agentx-0.195.1-darwin-arm64.tar.gz
echo "1f1d53b6db453d4e2be60b0aa83022c93edc04ab45c9444aea1c3e668b2858ec  agentx-0.195.1-darwin-arm64.tar.gz" | shasum -a 256 -c
tar xzf agentx-0.195.1-darwin-arm64.tar.gz && cd agentx-0.195.1-darwin-arm64 && ./install.sh --launchd
```

#### Mac, Intel (x86_64): `agentx-0.195.1-darwin-amd64.tar.gz`

- Download: https://app.agentxhq.io/releases/agentx-0.195.1-darwin-amd64.tar.gz
- SHA256: `0df5874a26572a729a820baef8e3f2c1038fe066861799ff089498818a9f7454`

```sh
curl -fLO https://app.agentxhq.io/releases/agentx-0.195.1-darwin-amd64.tar.gz
echo "0df5874a26572a729a820baef8e3f2c1038fe066861799ff089498818a9f7454  agentx-0.195.1-darwin-amd64.tar.gz" | shasum -a 256 -c
tar xzf agentx-0.195.1-darwin-amd64.tar.gz && cd agentx-0.195.1-darwin-amd64 && ./install.sh --launchd
```

### Linux

Use the package below for the distribution, flavor and architecture you picked in Step 2. `uname -m` prints `x86_64` on amd64 machines and `aarch64` on arm64 machines. Install only one flavor. If none of the packages below matches the machine, tell the person and stop. Don't use a package for a different distribution or architecture.

1. Download the package and check its checksum with the first two commands for it. Only continue if the check prints `<filename>: OK`. If it doesn't, the download is corrupt or isn't the file AgentX published, so don't install it.
2. Install it with the third command. It needs `sudo`, so ask first, as the Rules say. For the desktop flavor, AgentX must run as the person's login user, not as root. Run the command with `sudo` from that user's own shell. If you're already running as root, put `AGENTX_DESKTOP_USER=<their login name>` in front of the install command.

#### Debian / Ubuntu, desktop, amd64: `agentx-desktop_0.195.1_amd64.deb`

- Download: https://app.agentxhq.io/releases/agentx-desktop_0.195.1_amd64.deb
- SHA256: `7f40062f4b577d7c13f915c070b038d4b7898d008b3bcb601bd5fc9a6a755feb`

```sh
wget https://app.agentxhq.io/releases/agentx-desktop_0.195.1_amd64.deb
echo "7f40062f4b577d7c13f915c070b038d4b7898d008b3bcb601bd5fc9a6a755feb  agentx-desktop_0.195.1_amd64.deb" | sha256sum --check
sudo apt install ./agentx-desktop_0.195.1_amd64.deb
```

#### Debian / Ubuntu, desktop, arm64: `agentx-desktop_0.195.1_arm64.deb`

- Download: https://app.agentxhq.io/releases/agentx-desktop_0.195.1_arm64.deb
- SHA256: `3a01fece3dc9ebf62307e9eda96edb8319419b6a3c5b2c9eeb01fc00c1ffbe3a`

```sh
wget https://app.agentxhq.io/releases/agentx-desktop_0.195.1_arm64.deb
echo "3a01fece3dc9ebf62307e9eda96edb8319419b6a3c5b2c9eeb01fc00c1ffbe3a  agentx-desktop_0.195.1_arm64.deb" | sha256sum --check
sudo apt install ./agentx-desktop_0.195.1_arm64.deb
```

#### Debian / Ubuntu, server, amd64: `agentx-server_0.195.1_amd64.deb`

- Download: https://app.agentxhq.io/releases/agentx-server_0.195.1_amd64.deb
- SHA256: `9510fb950d3171d855c5faf22235a01008e248fc38ae8cf6bebcae3f8cbd8c5c`

```sh
wget https://app.agentxhq.io/releases/agentx-server_0.195.1_amd64.deb
echo "9510fb950d3171d855c5faf22235a01008e248fc38ae8cf6bebcae3f8cbd8c5c  agentx-server_0.195.1_amd64.deb" | sha256sum --check
sudo apt install ./agentx-server_0.195.1_amd64.deb
```

#### Debian / Ubuntu, server, arm64: `agentx-server_0.195.1_arm64.deb`

- Download: https://app.agentxhq.io/releases/agentx-server_0.195.1_arm64.deb
- SHA256: `486645ef37044f0a9357a9c044bb0e5f62e8e79d897e4d32c1cf6233b307589f`

```sh
wget https://app.agentxhq.io/releases/agentx-server_0.195.1_arm64.deb
echo "486645ef37044f0a9357a9c044bb0e5f62e8e79d897e4d32c1cf6233b307589f  agentx-server_0.195.1_arm64.deb" | sha256sum --check
sudo apt install ./agentx-server_0.195.1_arm64.deb
```

#### Arch, desktop, x86_64: `agentx-desktop-0.195.1-1-x86_64.pkg.tar.zst`

- Download: https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1-x86_64.pkg.tar.zst
- SHA256: `efb75cd2ed36e1bc683fcd37067a81ab132596a739d0f16b81bce2614f68f64e`

```sh
wget https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1-x86_64.pkg.tar.zst
echo "efb75cd2ed36e1bc683fcd37067a81ab132596a739d0f16b81bce2614f68f64e  agentx-desktop-0.195.1-1-x86_64.pkg.tar.zst" | sha256sum --check
sudo AGENTX_DESKTOP_USER="$USER" pacman -U ./agentx-desktop-0.195.1-1-x86_64.pkg.tar.zst
```

#### Arch, desktop, aarch64: `agentx-desktop-0.195.1-1-aarch64.pkg.tar.zst`

- Download: https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1-aarch64.pkg.tar.zst
- SHA256: `c08d889f0bea52a9447f31d7f7f35b6a97a473be539154df604b845c58556843`

```sh
wget https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1-aarch64.pkg.tar.zst
echo "c08d889f0bea52a9447f31d7f7f35b6a97a473be539154df604b845c58556843  agentx-desktop-0.195.1-1-aarch64.pkg.tar.zst" | sha256sum --check
sudo AGENTX_DESKTOP_USER="$USER" pacman -U ./agentx-desktop-0.195.1-1-aarch64.pkg.tar.zst
```

#### Arch, server, x86_64: `agentx-server-0.195.1-1-x86_64.pkg.tar.zst`

- Download: https://app.agentxhq.io/releases/agentx-server-0.195.1-1-x86_64.pkg.tar.zst
- SHA256: `25ffd24d35b9ef3a41e82d14bf6f12c412b47d999353141a8a94a4756fef827f`

```sh
wget https://app.agentxhq.io/releases/agentx-server-0.195.1-1-x86_64.pkg.tar.zst
echo "25ffd24d35b9ef3a41e82d14bf6f12c412b47d999353141a8a94a4756fef827f  agentx-server-0.195.1-1-x86_64.pkg.tar.zst" | sha256sum --check
sudo pacman -U ./agentx-server-0.195.1-1-x86_64.pkg.tar.zst
```

#### Arch, server, aarch64: `agentx-server-0.195.1-1-aarch64.pkg.tar.zst`

- Download: https://app.agentxhq.io/releases/agentx-server-0.195.1-1-aarch64.pkg.tar.zst
- SHA256: `4712f6509d9cff8fec14ebf5823108a6ede24d8e175dbdd03854c11705430815`

```sh
wget https://app.agentxhq.io/releases/agentx-server-0.195.1-1-aarch64.pkg.tar.zst
echo "4712f6509d9cff8fec14ebf5823108a6ede24d8e175dbdd03854c11705430815  agentx-server-0.195.1-1-aarch64.pkg.tar.zst" | sha256sum --check
sudo pacman -U ./agentx-server-0.195.1-1-aarch64.pkg.tar.zst
```

#### RHEL / Rocky / Alma, desktop, x86_64: `agentx-desktop-0.195.1-1.x86_64.rpm`

- Download: https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1.x86_64.rpm
- SHA256: `400cdcdac4fb40000bab29546d356770a6f1ca31e57ea6d70ce8474b89899c0e`

```sh
wget https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1.x86_64.rpm
echo "400cdcdac4fb40000bab29546d356770a6f1ca31e57ea6d70ce8474b89899c0e  agentx-desktop-0.195.1-1.x86_64.rpm" | sha256sum --check
sudo dnf install ./agentx-desktop-0.195.1-1.x86_64.rpm
```

#### RHEL / Rocky / Alma, desktop, aarch64: `agentx-desktop-0.195.1-1.aarch64.rpm`

- Download: https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1.aarch64.rpm
- SHA256: `439efd7fa99ab7fb83350fcd37280dee94f1807d6c0291dd7f2467fec0a8702c`

```sh
wget https://app.agentxhq.io/releases/agentx-desktop-0.195.1-1.aarch64.rpm
echo "439efd7fa99ab7fb83350fcd37280dee94f1807d6c0291dd7f2467fec0a8702c  agentx-desktop-0.195.1-1.aarch64.rpm" | sha256sum --check
sudo dnf install ./agentx-desktop-0.195.1-1.aarch64.rpm
```

#### RHEL / Rocky / Alma, server, x86_64: `agentx-server-0.195.1-1.x86_64.rpm`

- Download: https://app.agentxhq.io/releases/agentx-server-0.195.1-1.x86_64.rpm
- SHA256: `04cfb878ed968b2a5de92cbd13e70c2cf1f6edb81ff68d573a143568976da79a`

```sh
wget https://app.agentxhq.io/releases/agentx-server-0.195.1-1.x86_64.rpm
echo "04cfb878ed968b2a5de92cbd13e70c2cf1f6edb81ff68d573a143568976da79a  agentx-server-0.195.1-1.x86_64.rpm" | sha256sum --check
sudo dnf install ./agentx-server-0.195.1-1.x86_64.rpm
```

#### RHEL / Rocky / Alma, server, aarch64: `agentx-server-0.195.1-1.aarch64.rpm`

- Download: https://app.agentxhq.io/releases/agentx-server-0.195.1-1.aarch64.rpm
- SHA256: `b546dc80845540064d0c0f125dc2ed878b264538560e6e78390f1b9c00f404da`

```sh
wget https://app.agentxhq.io/releases/agentx-server-0.195.1-1.aarch64.rpm
echo "b546dc80845540064d0c0f125dc2ed878b264538560e6e78390f1b9c00f404da  agentx-server-0.195.1-1.aarch64.rpm" | sha256sum --check
sudo dnf install ./agentx-server-0.195.1-1.aarch64.rpm
```

The package enables and starts AgentX (server: system unit `agentx.service`;
desktop: user unit `agentx-daemon.service` with linger).

### Windows

Use the installer below for the flavor you picked in Step 2. If the person would rather use containers, follow https://www.agentxhq.com/install/docker instead.

Use the native package in Step 4 first. Docker is the alternative. The published image is linux/amd64 only. On a Mac or on Windows, pull and run it with `--platform linux/amd64`. Apple Silicon runs that platform by emulation. That emulation is best effort and does not always work. On Linux arm64, `docker pull --platform linux/arm64 agentxhq/agentx-daemon:latest` fails because there is no linux/arm64 image.

1. In PowerShell, download the installer and check it with the first two commands for it. Only continue if the check prints `True`. If it prints `False`, the download is corrupt or isn't the file AgentX published, so don't install it.
2. Install it with the third command. It installs without asking anything, waits until the installer is done, and prints its exit code. Only continue if it prints `0`. Otherwise show the person the last lines of `agentx-install.log`.
   - **Desktop:** run it in PowerShell as the person, not as administrator. AgentX starts when the install finishes and opens the claim page in the person's browser. It starts again each time they sign in, and it stops when they sign out.
   - **Server:** it needs PowerShell as administrator. Ask the person to open one (Start, type PowerShell, Run as administrator) and run it there, or ask first if you are already elevated. Without administrator rights the install fails. The AgentX service starts when the install finishes and starts with Windows.


#### Windows 10 / 11, x64, desktop: `agentx-desktop_0.195.1_amd64.msi`

- Download: https://app.agentxhq.io/releases/agentx-desktop_0.195.1_amd64.msi
- SHA256: `ce9472f47e8f9d8d99f8797ad64d80fcbf07c84d8be1abcb3a31825fe100dda1`

```powershell
curl.exe -fLO https://app.agentxhq.io/releases/agentx-desktop_0.195.1_amd64.msi
(Get-FileHash .\agentx-desktop_0.195.1_amd64.msi -Algorithm SHA256).Hash -eq 'ce9472f47e8f9d8d99f8797ad64d80fcbf07c84d8be1abcb3a31825fe100dda1'
(Start-Process msiexec.exe -ArgumentList "/i `"$PWD\agentx-desktop_0.195.1_amd64.msi`" /qn /l*v agentx-install.log" -Wait -PassThru).ExitCode
```

AgentX keeps its files in `%USERPROFILE%\.agentx` (Desktop) or `C:\ProgramData\AgentX` (Server). The Server folder is readable only by administrators.

#### Windows 10 / 11, x64, server: `agentx-server_0.195.1_amd64.msi`

- Download: https://app.agentxhq.io/releases/agentx-server_0.195.1_amd64.msi
- SHA256: `e546a3ddb15e1d7f1a9c70b47631977b553346abe8ed06180ddd3cd791e813f3`

```powershell
curl.exe -fLO https://app.agentxhq.io/releases/agentx-server_0.195.1_amd64.msi
(Get-FileHash .\agentx-server_0.195.1_amd64.msi -Algorithm SHA256).Hash -eq 'e546a3ddb15e1d7f1a9c70b47631977b553346abe8ed06180ddd3cd791e813f3'
(Start-Process msiexec.exe -ArgumentList "/i `"$PWD\agentx-server_0.195.1_amd64.msi`" /qn /l*v agentx-install.log" -Wait -PassThru).ExitCode
```

AgentX keeps its files in `%USERPROFILE%\.agentx` (Desktop) or `C:\ProgramData\AgentX` (Server). The Server folder is readable only by administrators.


## Step 5 — Get the claim link

While AgentX waits to be connected, it writes its claim code to a file, the
**claim file**. Read it on the computer where AgentX runs (on a VPS, over SSH):

| How AgentX runs | Command |
|---|---|
| Linux server (`agentx-server`) | `sudo cat /run/agentx/claim-token` |
| Linux desktop (`agentx-desktop`) or macOS | `cat ~/.agentx/run/claim-token`, as the person's login user |
| Windows Desktop | `Get-Content "$env:USERPROFILE\.agentx\run\claim-token"`, in PowerShell as the person |
| Windows Server | `Get-Content C:\ProgramData\AgentX\run\claim-token`, in PowerShell as administrator |
| Docker (Windows) | `docker exec agentx cat /run/agentx/claim-token` |

The file holds only the code. The claim link is:

```
https://www.agentxhq.com/daemons/claim?code=<CODE>
```

- If the file isn't there yet, wait a few seconds and try again. AgentX
  writes it once it has reached the account.
- If it stays missing, check AgentX's logs and show the person the exact
  error: `journalctl -u agentx` (Linux server),
  `journalctl --user -u agentx-daemon` (Linux desktop), `docker logs agentx`
  (Docker),
  on Windows Desktop `Get-Content -Tail 50 "$env:USERPROFILE\.agentx\log\agentx.log"`,
  on Windows Server `Get-Content -Tail 50 C:\ProgramData\AgentX\log\agentx.log` in PowerShell as administrator
  (`sc.exe query AgentX` shows a failed start as a non-zero `SERVICE_EXIT_CODE`),
  or on Mac, `~/.agentx/log/launchd.err.log` if it was installed
  without Homebrew, `$(brew --prefix)/var/log/agentx.log` if it was started with
  `brew services`, otherwise the `logfile:` path that `agentx-daemon status`
  prints.
- A code expires and is replaced, so read the file again right before you answer.
  The file is deleted once this computer is connected.

**Your final answer is the claim link, on its own line.** Tell the person to open
it, sign in to AgentX, and confirm. This computer then joins their account, and the
console walks them through creating their first agent.

## Upgrade an installed AgentX

Use this section only when AgentX is already installed on the machine and the
person asked you to upgrade it. Step 0 still applies: you must be running
commands on that machine. The Rules still apply, too.

An upgrade keeps this computer's enrollment, its agents and their workspaces, as long
as you install the same flavor that's there now. Never switch between desktop and
server: they keep their files in different places, and AgentX would come back
as a new, unconnected install.

**Read this before you start.** You are probably running on the very AgentX service you
are upgrading. When that AgentX service stops or restarts, your session ends with it, and
anything you started from it may be killed. So never stop or restart the AgentX service
directly from your own session. Use only the commands below: either they keep
running after your session ends, or the person runs them. You may not see the
upgrade finish. Before the step that restarts AgentX, tell the person that
your session will end there and that AgentX will start again on the new
version. If you're resumed afterwards, run U4 again. Don't trust the result of a
command you ran before the restart.

### U1 — Find what's installed

Make sure you're on the machine the person asked you to upgrade. If you're not
sure, ask them. Then find out how AgentX was installed:

| How AgentX runs | Check |
|---|---|
| Linux server | `dpkg -s agentx-server`, `rpm -q agentx-server` or `pacman -Q agentx-server` finds it |
| Linux desktop | `dpkg -s agentx-desktop`, `rpm -q agentx-desktop` or `pacman -Q agentx-desktop` finds it |
| macOS with Homebrew | `brew list agentx` finds it |
| macOS without Homebrew | `~/.local/bin/agentx-daemon` exists |
| Windows Desktop | `Test-Path "$env:LOCALAPPDATA\AgentX\agentx-daemon.exe"` prints `True` |
| Windows Server | `Get-Service AgentX` finds the service |
| Docker | `docker ps --filter name=agentx` shows the container |

On macOS, also find out how AgentX is started:

- `launchctl print gui/$(id -u)/homebrew.mxcl.agentx` succeeds: it's the launchd job `homebrew.mxcl.agentx`.
- `launchctl print gui/$(id -u)/com.agentx.daemon` succeeds: it's the launchd job `com.agentx.daemon`.
- Neither succeeds: it was started with `agentx-daemon background`.

Note the version number it runs: `agentx-daemon version` prints `agentx v<version>`
(Windows Desktop: `& "$env:LOCALAPPDATA\AgentX\agentx-daemon.exe" version`;
Windows Server: `& 'C:\Program Files\AgentX\agentx-daemon.exe' version`; Docker:
`docker exec agentx agentx-daemon version`).

Note AgentX's process ID, so U4 can show it restarted:

| How AgentX runs | Process ID |
|---|---|
| Linux server | `systemctl show -p MainPID --value agentx` |
| Linux desktop | `systemctl --user show -p MainPID --value agentx-daemon` |
| macOS | `pgrep -x agentx-daemon` |
| Windows Desktop | `(Get-Process agentx-host).Id` |
| Windows Server | `(Get-CimInstance Win32_Service -Filter "Name='AgentX'").ProcessId` |
| Docker | not needed: the upgrade replaces the container |

Tell the person what you found.

The latest version is 0.195.1. If AgentX already runs it, tell the person and go to U4.

### U2 — Get the new package

For Linux, macOS without Homebrew and Windows: download the package for this
machine and check its checksum with the first two commands for it in Step 4.
Pick the same distribution, flavor and architecture that's installed now. Only
continue if the check passes. Don't run Step 4's install command: U3 says how to install.

### U3 — Install it

**Linux.** Ask before using `sudo`, as the Rules say. Then start the install as
its own system job, outside the AgentX service, from the folder with the package you
downloaded. Use the line for the flavor and distribution.

Server (`agentx-server`):

```sh
sudo systemd-run --unit=agentx-upgrade --collect apt-get install -y "$PWD/<filename>"
sudo systemd-run --unit=agentx-upgrade --collect dnf install -y "$PWD/<filename>"
sudo systemd-run --unit=agentx-upgrade --collect pacman -U --noconfirm "$PWD/<filename>"
```

Desktop (`agentx-desktop`), run from the person's own login so AgentX keeps
running as them:

```sh
sudo systemd-run --unit=agentx-upgrade --collect --setenv=AGENTX_DESKTOP_USER="$USER" apt-get install -y "$PWD/<filename>"
sudo systemd-run --unit=agentx-upgrade --collect --setenv=AGENTX_DESKTOP_USER="$USER" dnf install -y "$PWD/<filename>"
sudo systemd-run --unit=agentx-upgrade --collect --setenv=AGENTX_DESKTOP_USER="$USER" pacman -U --noconfirm "$PWD/<filename>"
```

The command returns at once, and the install goes on without you. The package
restarts AgentX, which ends your session.

If your account can't use `sudo`, or `sudo` asks for a password, stop. Don't try
to enter one. Give the person the exact same line to run in their own terminal
(over SSH on a server), from the folder with the package, and do U4 when they
tell you it's done.

**macOS.** First swap the program. This doesn't stop AgentX, so you run it:

- With Homebrew: `brew upgrade agentx`
- Without Homebrew: unpack the package with Step 4's `tar xzf … && cd …`, then run
  `./install.sh` **without** `--launchd`. Never run `./install.sh --launchd` for an
  upgrade: it stops AgentX, and your session with it, before it starts
  AgentX again.

Then restart AgentX, by how U1 found it is started:

- **The launchd job `homebrew.mxcl.agentx` or `com.agentx.daemon`:** run
  `launchctl kickstart -k gui/$(id -u)/<that job>`. launchd stops AgentX and
  starts it on the new program, which ends your session. Don't use
  `brew services restart` from your session.
- **Started with `agentx-daemon background`:** ask the person to run
  `agentx-daemon restart` in their own Terminal, and do U4 when they tell you
  it's done. Running it from your session would stop AgentX and not start it
  again.

**Windows.** The installer stops AgentX part-way through, which would end your
session and the installer with it, so the person runs it, not you. Ask them to
open PowerShell (Desktop: as themselves; Server: as administrator), go to the
folder with the installer you downloaded, and run:

```powershell
(Start-Process msiexec.exe -ArgumentList "/i `"$PWD\<filename>`" /qn /l*v agentx-upgrade.log" -Wait -PassThru).ExitCode
```

It upgrades in place, keeps this computer's connection to the account, its
agents and their files, and starts AgentX again on the new version. It must
print `0`. Use an installer newer than the one installed. An older one is refused
with "A newer AgentX is already installed." (Server: "A newer AgentX Server is
already installed.") Do U4 when they tell you it's done.
Use the same flavor that's installed now.

**Docker.** Ask the person to run this on the computer that runs Docker. It
keeps the same volumes, so the files are kept. A new container does not keep
Unix accounts of agents that have their own user. After it is running, recreate
each such account and give the home back:

```sh
docker pull --platform linux/amd64 agentxhq/agentx-daemon:latest && docker rm -f agentx && docker run -d --platform linux/amd64 --name agentx --restart unless-stopped -p 127.0.0.1:3333:3333 -v agentx-data:/var/lib/agentx -v agentx-root:/root -v agentx-home:/home agentxhq/agentx-daemon:latest
```

```sh
docker exec agentx useradd --create-home --home-dir /home/<account> --shell /bin/bash <account>
docker exec agentx chown -R <account>: /home/<account>
```

### U4 — Check the upgrade

When you're back, or when the person tells you they ran the command, check:

1. The installed version is the new one, with U1's version command.
2. AgentX restarted: U1's process ID command prints a number, and it's not
   the one you noted in U1. (Docker: `docker ps --filter name=agentx` shows the
   container running.) A new process started after the install runs the new
   version. The same process ID means AgentX is still running the old one.
3. The person sees this computer online in AgentX at https://www.agentxhq.com, and it's no
   longer listed as needing an upgrade.

If a check fails, stop and show the person the exact output. Don't install again
over it, and don't switch flavor. On Linux, `sudo journalctl -u agentx-upgrade`
shows how the install went. AgentX's logs are listed in Step 5. There is no
claim link for an upgrade: this computer is already in the person's account.

**Your final answer is the version AgentX now runs, and whether it's online.**
