Remove the Agent from a Device
Uninstall the octoja Agent on Windows, macOS, and Linux — and what deleting a device from the octoja inventory does on the machine itself.
This guide shows you how to remove the octoja Agent from a Windows, macOS or Linux device — and what happens in octoja when you do. There are two ways: delete the device in octoja and let the agent remove itself, or uninstall the agent locally on the machine.
Does deleting a device also uninstall the agent?
Yes. When you delete a device from the octoja inventory, the agent on that machine uninstalls itself:
On RHEL-family Linux devices (RPM package), the agent does not uninstall itself when you delete the device. Uninstall it manually there first (see Uninstall manually on Linux below), then delete the device entry.
The reverse is just as important: because deleting a device also uninstalls its agent, never delete a device entry just to tidy up your list while the agent should keep running on that machine.
Which way should you choose?
- The device is still managed and reachable: delete it in octoja. One step removes both the inventory entry and the agent — you do not need to uninstall first.
- The machine is already wiped or gone: delete the entry in octoja. Nothing else is needed.
- The machine stays in use, but without octoja: uninstall the agent locally (below), then delete the device entry once it shows as offline.
Delete the device in octoja
- In octoja, go to Devices and open the device.
- Open the … menu at the top right of the device page and choose Delete Device. You need the Delete Device permission to see this action.
- Confirm with Delete. octoja warns you before it proceeds — the deletion cannot be undone.
The device disappears from the Devices list, and the agent on the machine removes itself as described above.
Delete several devices at once
- Go to Devices, open the table's … menu and switch on Multiselect. The row checkboxes appear only once it is on.
- Tick every device you want to remove.
- In the selection bar, open More actions and choose Delete.
- Type
DELETEand confirm with Delete devices.
Each device is removed exactly as in the single-device flow, and every agent uninstalls itself as described above. Devices you do not hold the Delete Device permission for are skipped — the confirmation dialog tells you how many.
Uninstall manually on Windows
- On the device, open Settings → Apps → Installed apps.
- Find octoja Agent (publisher: octoja GmbH) and select Uninstall.
The uninstaller stops and removes both agent services (Octoja Agent and Octoja Launcher) and the scheduled task octoja Service Recovery, which restarts stopped agent services every five minutes. It also deletes the program files and the connection settings.
No octoja Agent entry in the list? The device may have Prevent local uninstall switched on. That setting is off by default; while it is on, the agent hides its entry from Add/Remove Programs so nobody can uninstall it with one click. It is a deterrent, not a hard block: deleting the device in octoja still uninstalls the agent, and the msiexec /x command below still works. To bring the entry back, open the device in octoja, choose Agent settings from the … menu and switch Prevent local uninstall off — or turn it off in the configuration package that enables it. The setting only takes effect on Windows; on macOS and Linux it does nothing.
For an unattended removal — for example through your software deployment tooling — use the MSI you installed with:
msiexec /x octoja.Launcher.<version>.<arch>.msi /qn
What stays behind: the uninstaller deletes the connection settings from C:\ProgramData\octoja GmbH and removes the folder once it is empty. If you installed with the setup script, its install.log remains there — delete the folder by hand for a completely clean machine.
The device identity is not kept in that folder. On Windows the agent stores it in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\Octo\Launcher, where it survives the uninstall: install the agent on this machine again and it enrolls with the same identity, so the machine comes back as the same device in octoja instead of a second entry.
Uninstall manually on macOS
The agent ships with its own uninstall script. Open Terminal (Applications → Utilities → Terminal) and run:
sudo /opt/octoja/uninstall.sh
The script stops both agent services (com.octoja.launcher and com.octoja.agent) and the recovery job com.octoja.service-recovery, removes their entries from /Library/LaunchDaemons, deletes the entire /opt/octoja folder and removes the macOS package receipt. The agent keeps all of its files, settings and logs under /opt/octoja, so nothing is left behind — this is the complete removal.
Uninstall manually on Linux
The agent is installed as the package octoja. Remove it with your distribution's package manager. Removal automatically stops and disables the two services (octoja-launcher and octoja-agent) and the recovery timer octoja-service-recovery.timer.
Debian and Ubuntu
sudo apt purge octoja
Note the difference between the two package-manager commands:
If you work with dpkg directly, sudo dpkg -P octoja is the equivalent of the purge command.
RHEL family (RPM)
sudo dnf remove octoja
Alternatively, sudo rpm -e octoja removes the package. This removes the programs, the services and the data and log files under /opt/octoja. There is no purge command: the configuration in /etc/octoja stays on disk, and leftovers can remain under /opt/octoja. For a complete removal, delete both folders afterwards:
sudo rm -rf /opt/octoja /etc/octoja
Afterwards in octoja
If you deleted the device in octoja, you are done — the entry is gone from your list and the deletion cannot be undone.
If you uninstalled the agent locally instead, the device entry stays in octoja: it switches to offline shortly afterwards and stops reporting data. Delete the entry from the device page (see above) whenever you are ready. If you keep it, it stays an offline device in your list.
To bring a device back later, install the agent again through the normal deployment flow — see the guides below.
Check the enrollment token before doing so: a customer-bound token replaces the customer and site on re-enrollment, even when octoja recognises the device by its existing identity. A token with a customer but no site clears the previous site. Without a customer-bound token, a valid existing assignment is preserved. This also applies when restoring a deleted device. See Configure Agent Enrollment Tokens for the full rules.
Related articles
Was this helpful?
Still need help? Ask the team