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.

Written By Stefan Steuer

Last updated 25 days ago

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:

The device is …What happens
onlineThe agent is notified immediately, runs its platform uninstaller and removes itself within moments.
offlineThe agent uninstalls itself the next time it connects to octoja.
gone for good (wiped, sold, scrapped)Nothing can trigger the removal on the machine anymore. If the machine still exists, uninstall the agent manually — see the platform sections below.

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

  1. In octoja, go to Devices and open the device.
  2. 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.
  3. 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.

Uninstall manually on Windows

  1. On the device, open Settings → Apps → Installed apps.
  2. Find octoja Agent (publisher: octoja GmbH) and select Uninstall.

The uninstaller stops and removes both agent services (Octoja Agent and Octoja Launcher) and deletes the program files and the connection settings.

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

For a completely clean machine: a small data folder at C:\ProgramData\octoja GmbH remains after uninstalling. Among other things, it contains the device identity file the agent created during enrollment. Delete the folder manually — especially before you install the agent on this machine again from scratch.

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), 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 the package manager:

sudo apt purge octoja

The two services (octoja-launcher and octoja-agent) are stopped and disabled automatically during removal. Note the difference between the two package-manager commands:

CommandWhat it removes
sudo apt remove octojaPrograms and services only — the configuration in /etc/octoja and the files under /opt/octoja stay on disk.
sudo apt purge octojaEverything, including /opt/octoja and /etc/octoja. Use this for a complete removal.

If you work with dpkg directly, sudo dpkg -P octoja is the equivalent of the purge command.

Afterwards in octoja

If you deleted the device in octoja, you are done — the entry is gone and cannot be restored.

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 simply remains 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.