The agent Deployment
Deployment
Enrolling a machine
Go to Inventory › Machines → Enroll machines.
- Profile. Choose or create an enrollment profile. This fixes the machine's capture strategies for its whole life — see Capture strategies for what each one does. A new profile is set up on a Configure step first.
- Install. Get a credential from that profile. How many machines? offers two kinds:
- One machine. An install command that works once — it enrols exactly one machine, then it is spent. The server only keeps its digest, so it cannot show it again.
- Many machines (MDM). A reusable secret for a managed-configuration push, bounded by a maximum enrolment count and an expiry.
The command the console generates
Minting the one-liner prints a command for each shell. Both download the installer straight from the console, so if your workspace has allowlisted the console, nothing else needs allowlisting.
What a successful install looks like
Run the command as an administrator: an elevated PowerShell on Windows, sudo
in front of sh on macOS and Linux. The installer:
- verifies the release it downloads, then places the agent on the machine
- exchanges the token for a machine identity — a private key generated locally, and never sent anywhere
- registers the agent as a service that starts with the machine: a Windows service, a launchd daemon on macOS, a systemd unit on Linux
It ends with a box titled Installed, naming the machine, its workspace and the service. Anything that still needs a person — no tray icon, no tool hooks, a certificate that is not trusted yet — is listed in the same box under Needs attention.
A machine that already has an agent
The installer stops before it spends the token, and says what it found. Replacing an enrolled agent needs that machine's removal key as well as the new token:
The previous agent is removed first, and the new enrollment is linked to the machine it replaces.
Uninstall
Open the machine, then Lifecycle (under More), and choose Issue key. The removal key belongs to that one machine. It is shown once: the server keeps only its digest. Issuing another key invalidates the one before it, and a key stops working once its machine is uninstalled or deleted.
Run the command on the machine itself, as an administrator:
The script hands the removal to the installed agent. On macOS and Linux it still works when that agent will not run: it fetches a verified one from the server to do the removal. Where the agent is healthy, its own command does the same thing:
Uninstall removes everything the agent put on the machine: the certificate authority, the proxy setting, every network route and the TUN adapter, the browser force-install policy, the hooks it added to each CLI and IDE tool's managed settings, and every restriction value it wrote into a tool's managed policy. Entries other people put in the same files are left exactly as they were.
A tool is never left broken by the agent stopping or going away: a hook lets the action through when the agent is not installed or not running, and a stopped agent takes its hooks out first. A tool that was already open picks the change up the next time it starts.
A crashed agent is put right by the service manager, which removes the hooks and the trust entries before the agent restarts. The root certificate is kept, as before.