Detaching ends an agent's relationship with its DPLens Manager. The agent goes back to being a standalone agent that you manage on the machine, and it keeps collecting and delivering throughout.
There are two ways to do it.
From the Manager
When the Manager detaches or retires an agent, it sends the agent a signed instruction at its next check-in; the agent acts on nothing less. This is the normal route, because the agent's last check-in tells the Manager it has left, so the Manager can release its licence seat.
On the machine
When the Manager is gone, unreachable, or you need the machine back now, an administrator can detach it locally. From an elevated prompt, with the service stopped:
sc.exe stop dplens
"C:\Program Files\DPLens\dplens.exe" --detach
sc.exe start dplens
It needs no network and no Manager, takes no other argument — there is no force option — and is recorded in the audit log under the account that ran it. It refuses while the service is running, and also while any other DPLens process is still running the agent on this machine.
| Exit code | Meaning |
|---|---|
| 0 | Detaching — or the agent was already detaching. Start the service. |
| 1 | A step failed — the line names it — or the prompt is not elevated. |
| 2 | Wrong usage. --detach takes no options. |
| 4 | The service control manager could not be asked whether the service runs. |
| 5 | The service — or another DPLens process running the agent on this machine — is running. Stop it first. |
| 7 | This agent is not enrolled. Nothing was changed. |
What happens
At once:
- The agent is no longer managed. Every console action works again.
- The licence lease from the Manager is discarded. If the machine has its own licence key, that key applies again; if it has none, collection is held until you apply one — see Licensing.
- The configuration the Manager last applied is kept as the machine's own configuration, and collection carries on under it.
- Secrets the Manager delivered become ordinary local secrets, so the configuration keeps working after the next restart. Each one is recorded in the audit log, and their names are reported to the Manager. From this moment those credentials are outside fleet control — the Manager can no longer rotate or revoke them on this machine. Rotate them at their source, especially if the machine is leaving your estate.
A local detach does the secret conversion, and sends the last check-in, when the service next starts.
Then: the agent makes one last check-in to tell the Manager it is leaving. It keeps trying for up to 24 hours. The detach completes when the Manager acknowledges it, when the Manager reports the agent as retired, or when the 24 hours run out — whichever comes first.
If a step of the clean-up fails — a file that cannot be deleted, say — nothing is left half-done: the agent records the failure in the audit log and finishes the clean-up at every start until it succeeds. When it completes, the agent deletes what it held for the Manager: its enrolment, the Manager's trust material, its place in the Manager's command sequence, telemetry not yet sent, and cached configuration templates. Its two identity keys are deleted too, so the machine can never again present the identity it had. It keeps the Manager's address, CA pin and pool id, and everything that was never the Manager's: your configuration, local secrets, the audit log, collection positions and destination caches.
Enrolling it again
Once the detach has completed, enrol with a new token. Until it has, --enrol refuses with detach_in_progress (exit code 8): start the service once so the detach can finish, then enrol. Because the Manager address, pin and pool id are kept, the token is all the agent needs:
sc.exe stop dplens
Get-Content C:\secure\enrol.json | & "C:\Program Files\DPLens\dplens.exe" --enrol
sc.exe start dplens
with enrol.json holding {"enrol_token":"DPET1.<…>"}. The agent creates a new identity, so the Manager sees a new agent. See Enrolling an agent with DPLens Manager.
Detaching by uninstalling
Uninstalling DPLens always removes everything the agent held for the Manager, including its identity — with or without REMOVE_STATE. It does not send the final check-in, so the Manager sees the agent go silent; retire it there. See Upgrading and uninstalling.