Deploy the Desktop Agent on Linux (Ansible / .deb)

The ZeusLock desktop agent runs in each user's graphical session — a tray app plus a local inspection proxy on 127.0.0.1:9876. This guide rolls it out to your Linux desktop fleet with Ansible (or by hand for a single machine) and binds every machine to your organization through a config file.

Scope: the agent protects interactive desktop use of AI tools. It is not meant for headless servers — with no desktop session there is nothing to protect.

How binding works

The package you download is generic and carries no credentials. A machine is only bound to your organization once you deliver two configuration values separately:

• ServerUrl — your tenant API URL, for example https://api.zeuslock.ai.
• LicenseKey — your organization API key from Settings → API Keys (a zl_... value).

You do not configure what blocks versus alerts on the endpoint. The policy lives in the ZeusLock dashboard and the agent fetches it using the LicenseKey.

Prerequisites

• Target machines run a Debian-family desktop (Ubuntu, Debian, Linux Mint…) with a graphical session and outbound HTTPS access to your ServerUrl.
• For the Ansible path: a control node with SSH and sudo on the targets.
• The Linux package from the dashboard — Agents → Download, Linux. You get a .deb (for example zeuslock-desktop-agent_<version>_amd64.deb; an arm64 build is also available).

Step 1 — Deploy with Ansible

Use the ready-made playbook from the deployment repository: it copies and installs the .deb, writes /etc/zeuslock/agent.conf, and adds a desktop autostart entry so the agent launches in each user's session. Set your two values in the vars: block (or pass them with -e):

vars:
  zeus_server_url: "https://api.zeuslock.ai"
  zeus_license_key: "zl_..."          # keep this in an Ansible Vault variable
  zeus_deb_src: "./zeuslock-desktop-agent_amd64.deb"

ansible-playbook -i inventory.ini zeuslock-agent.yml --ask-become-pass

The playbook is idempotent — re-running it only changes what drifted. Store the license key with ansible-vault encrypt_string rather than in plain text.

Step 2 — The configuration file

The managed configuration is a simple KEY=VALUE file at /etc/zeuslock/agent.conf (owned root:root, mode 0644) — the playbook writes it for you; for other tooling deploy it yourself:

ServerUrl=https://api.zeuslock.ai
LicenseKey=zl_your_org_api_key
# Optional toggles (defaults shown):
AgentEnabled=true
BlockingEnabled=true
NetworkMonitoring=true
FileMonitoring=true

A JSON fallback at /etc/zeuslock-dlp/config.json is also supported (used when the managed file did not supply a license key) — same ServerUrl/LicenseKey keys as on Windows and macOS.

Install on a single machine by hand

For a pilot — also the recommended first test before a fleet push — use the install script from the deployment repository:

# Edit the two values at the top of the script, then:
sudo bash install-zeus-agent.sh ./zeuslock-desktop-agent_amd64.deb

It installs the package, writes /etc/zeuslock/agent.conf, and adds the autostart entry. Log out and back in — or launch ZeusLock - AI Data Protection from the app menu — to start the agent in your session.

Verify

On a target machine, with a user logged into the desktop:

dpkg -l | grep -i zeus                 # installed?
sudo cat /etc/zeuslock/agent.conf      # config delivered?
pgrep -fa zeus | head                  # agent running in the session?
ss -ltnp | grep 9876                   # inspection proxy listening?

Then run a live test: in the browser, paste a test card number such as 4111 1111 1111 1111 into chatgpt.com and confirm an incident appears in the dashboard under Incidents.

Removing the agent

sudo apt-get remove -y zeuslock-desktop-agent
sudo rm -f /etc/zeuslock/agent.conf /etc/zeuslock-dlp/config.json
sudo rm -f /etc/xdg/autostart/zeuslock-agent.desktop

Full guide and templates

For the complete walkthrough with the ready-made Ansible playbook, install script, config templates, and troubleshooting checklist, see the deployment repository at https://github.com/Zeuslock-ORG/zeuslock-agent-deployment.