# Install AgentX — instructions for AI assistants You are helping a person install AgentX. AgentX runs a small program, the **daemon**, on a machine the person controls. The daemon 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**. 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). | 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 | Docker Desktop (WSL 2) — see https://www.agentxhq.com/install/docker | 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. 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 the daemon ### macOS 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. Open https://www.agentxhq.com/install, choose Mac, and use **Without Homebrew**. It has the current package for Apple Silicon and Intel Macs, with its download command and checksum. 1. Download the package that matches the Mac: `uname -m` prints `arm64` (Apple Silicon) or `x86_64` (Intel). 2. Check it with the `shasum -a 256 -c` command shown there. Only continue if it prints `OK`. 3. Unpack it and run `./install.sh --launchd`. This installs `agentx-daemon` and `agentx` into `~/.local/bin` (no sudo) and starts the daemon now and at every login. 4. If the person downloaded it in a browser instead, run `xattr -dr com.apple.quarantine .` in the unpacked folder before step 3. ### Linux Open https://www.agentxhq.com/install and use the **Manual install** section. It has the current package for each distribution, flavor and architecture, with its download command and checksum. 1. Download the package that matches Step 2. 2. Check its checksum with the `sha256sum --check` command shown there. Only continue if it prints `OK`. If the check fails, the download is corrupt or isn't the file AgentX published, so don't install it. 3. Install it with the command shown for your distribution and flavor. For the desktop flavor, set `AGENTX_DESKTOP_USER` to the person's login user as shown there, so the daemon runs as them and not as root. The package enables and starts the daemon (server: system unit `agentx.service`; desktop: user unit `agentx-daemon.service` with linger). ### Windows Follow https://www.agentxhq.com/install/docker. ## Step 5 — Get the claim link While the daemon waits to be claimed, it writes its claim code to a file, the **claim file**. Read it on the machine where the daemon runs (on a VPS, over SSH): | How the daemon 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 | | 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= ``` - If the file isn't there yet, wait a few seconds and try again. The daemon writes it once it has reached AgentX. - If it stays missing, check the daemon'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), 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 the daemon is claimed. **Your final answer is the claim link, on its own line.** Tell the person to open it, sign in to AgentX, and confirm. The daemon then joins their account, and the console walks them through creating their first agent.