Install the desktop agent with your own AI assistant

Paste this prompt into the coding assistant you already use (Claude Code, Codex, Cursor or similar) on the machine that will run the Badgeye agent. It installs the agent, enrols it, and checks the result step by step.

You need

An invite token and the API URL from your Badgeye admin (the URL ends in /api).
Admin rights on the machine, and outbound HTTPS.

What it will not do

It never asks you to paste the token, a password or a key into the chat: you type the token yourself at a hidden prompt.
It does not turn off antivirus, the firewall, Gatekeeper, SmartScreen or certificate checks.
It checks the installer's checksum and signature before running it, and ends by running badgeye-agent doctor, a read-only scan that changes nothing.

Install prompt (select all and copy)

You are helping an IT administrator install the Badgeye desktop agent on THIS machine. Work in small steps, run each check, and report the result in one line before moving on. Rules you must follow:

1. Never ask the administrator to paste the invite token, a password, an API key or a TOTP seed into this chat, and never write one into a file, a command line argument, a shell history or a log. When the agent needs the invite token, tell the administrator to run the enrol command themselves in their own terminal and type the token at the hidden prompt (or set it in the environment of that one command). If you see a secret in any output, stop, say so, and do not repeat it.
2. Do not disable antivirus, firewall, Gatekeeper, SmartScreen, proxy or TLS checks. If a download or certificate fails, report it and stop; do not use `--insecure`, `-k`, `curl | sh`, or an unsigned build. The only exception is a local test against `http://localhost`, and only if the administrator says it is a test.
3. Make no change outside the steps below. Ask before installing anything not listed.

Step 1. Detect the machine. Report OS and version, CPU (arm64/x86_64), whether you have admin rights, free disk space (need at least 2 GB), and whether the clock is synchronised. Stop if the OS is not macOS, Windows 10/11 x64, or Linux with systemd.

Step 2. Check the network (outbound HTTPS only, no inbound ports). Using the API URL the administrator gives you, confirm its host resolves and that `https://<host>` answers with a valid certificate. If a corporate proxy is in use, tell the administrator the proxy variables or `BADGEYE_WORKSTATION_LINK_CA_FILE` they may need, and stop until they confirm.

Step 3. Get the installer ONLY from the administrator's Badgeye release page or the official GitHub Release they name. Verify its SHA-256 against `SHA256SUMS.txt` from the same release, and on macOS/Windows confirm the signature (`pkgutil --check-signature`, or the file's Digital Signatures tab / `Get-AuthenticodeSignature`). Report the checksum and signer. Stop if either does not match.

Step 4. Install.
- macOS: open the `.pkg`. It installs `/usr/local/badgeye`, the command `badgeye-agent`, and a per-user LaunchAgent.
- Windows: run the `.msi` (or `msiexec /i <file> /qn` with the token supplied by the administrator as a hidden property, not typed by you).
- Linux: unpack the tarball and run `./install.sh` for a per-user systemd unit.
Then run `badgeye-agent --version` and report it.

Step 5. Enrol. Tell the administrator to run, in their own terminal, `badgeye-agent enrol --url https://<host>/api` and enter the token when prompted (or have it in `BADGEYE_ENROL_TOKEN` for that one command). Do not run it for them with a token in the command. Then run `badgeye-agent status` and report the agent id and org id it prints (these are not secrets).

Step 6. Browser. Run `badgeye-agent install-browser` (one-time Chromium download, about 150 MB to `~/.badgeye-agent/browsers`). Report success. If the network blocks the Playwright CDN, tell the administrator about `PLAYWRIGHT_DOWNLOAD_HOST` (a mirror) and stop.

Step 7. Start at login and run. Confirm the service is registered (macOS: `launchctl list | grep badgeye`; Windows: `schtasks /Query /TN BadgeyeAgent`; Linux: `systemctl --user status badgeye-agent`). Start it if it is not running.

Step 8. Verify with the built-in scanner. Run `badgeye-agent doctor` (read-only; it changes nothing). Report every line marked WARN or FAIL, with its suggested fix. Exit code 0 means all clear, 1 warnings, 2 failures. Do not try to fix a FAIL by editing the agent's database or config by hand; apply the printed fix or stop and report. Also run `badgeye-agent doctor --json` and keep the output for the ticket (it holds ids and counts only, no secrets).

Step 9. Confirm in the console. Ask the administrator to open the Badgeye console, go to the agents page, and check this machine shows as online with the version you saw. Do not log in to the console for them.

Known failure modes, check these first when something fails:
- Enrol says the token is invalid or expired: tokens last 24 hours and work once; ask the admin for a new one.
- Enrol refuses a URL: it must start with `https://` and end in `/api`.
- "clock skew" in doctor: turn on automatic time; signed approvals and sessions depend on it.
- macOS prompts for the login keychain: allow it; the vault key lives there (service `badgeye-vault`).
- Chromium will not download: proxy or CDN block (see Step 6).
- Agent shows offline after a restart: run `badgeye-agent doctor`, then look at the service log; do not reinstall until doctor has been read.
- Intranet apps are unreachable by design. Only exact hostnames or IPs listed in `BADGEYE_BROWSER_INTRANET_ALLOW` (set by the administrator) are allowed; never wildcards, and never loopback or cloud-metadata addresses.

When done, give the administrator a short summary: version, agent id, doctor result, and anything that still needs a person. Do not include any secret.

Prefer to install by hand? The steps are in the agent install guide.

Want to see it work first?

← Badgeye