Deploy the Endpoint Agent

How to roll the endpoint agent to real user machines, and what to arrange before you start. Read the fleet-rollout section before deploying at scale — two of the items there are easier to arrange in advance than to explain afterwards.

Prerequisites

Requirement	Detail
Python	3.9 or newer, already present on macOS and most Linux
python3-venv	Debian/Ubuntu only — a separate package. apt install python3-venv
Privileges	root / Administrator. The installer writes to system service directories
Disk	~4 GB free (virtualenv, logs, and a 2.2 GB known-good hash corpus)
Network	HTTPS egress to the control plane and the corpus bucket (below)

Network egress

Allow both, or the agent installs cleanly and then quietly stops receiving detection data:

Destination	Port	Purpose
Your control plane	443	Enrollment, policy, telemetry, commands
*.your-objectstorage.com	443	Signed hash corpora (NSRL known-good, malware)

A blocked corpus URL is not an obvious failure. The agent keeps running on its last good corpus and reports the corpus as stale in its heartbeat — which is the intended behaviour, but only helps if someone is watching the Endpoints view for it.

Install

Download the package and issue a one-time bootstrap token from the customer portal (SDK & Onboarding), then:

unzip -q cyberarmor-endpoint-agent.zip -d cyberarmor-agent
cd cyberarmor-agent
sudo python3 installer.py install \
  --control-plane-url https://your-control-plane \
  --tenant-id your-tenant-id \
  --bootstrap-token cabt_...

The token is redeemed into an install-scoped credential during setup, so no shared tenant secret is embedded on the endpoint. It is shown once and expires.

macOS: grant Full Disk Access

Required. Skipping it produces an agent that reports healthy while monitoring nothing.

~/Documents, ~/Downloads, and ~/Desktop are TCC-protected. A daemon without Full Disk Access receives no file events from them at all — no error, no warning in the logs, heartbeats flowing normally. The endpoint looks protected and is not.

1. System Settings → Privacy & Security → Full Disk Access
2. Click +, press Cmd+Shift+G, enter /usr/local/cyberarmor/.venv/bin/, and add python3
3. Restart the agent — the grant does not apply to the running process:

sudo launchctl kickstart -k system/ai.cyberarmor.endpoint

:::note If python3 is greyed out and unselectable

macOS will not grant Full Disk Access to a symlink, and endpoints installed before 2026-08-11 have one there — python3 → python3.14 → /Library/Frameworks/…. The installer now builds the venv with --copies, so a reinstall puts a real binary at that path and scopes the grant to this agent.

Failing that, grant it to whatever the link resolves to (readlink -f /usr/local/cyberarmor/.venv/bin/python3) — but that gives Full Disk Access to every script that interpreter runs, machine-wide.

:::

The label is ai.cyberarmor.endpoint. Earlier revisions of this page said ai.cyberarmor.endpoint-agent, which has never existed: bootout answered "Could not find specified service" and bootstrap "No such file or directory", so the agent was never restarted and the grant silently did not take effect.

Verify

Do not rely on "the install said OK". Prove it:

sudo python3 /usr/local/cyberarmor/disk_access.py

Lists every monitored directory and exits non-zero if any is unreadable. For a deeper check that change notifications actually arrive — a separate permission from being able to read the directory:

sudo python3 /usr/local/cyberarmor/disk_access.py --canary

This writes a temporary dotfile into each monitored directory, confirms the event is observed, and removes it.

Then confirm enrollment in the customer portal under Endpoints. The host appears within about a minute, with Monitoring showing OK rather than Degraded.

Coexisting with an existing EDR

Most organisations already run CrowdStrike, SentinelOne, or Microsoft Defender. The CyberArmor agent monitors files, processes, and optionally the clipboard — behaviour that is, by design, difficult to distinguish from malware.

Arrange an exclusion before deployment, not after. Expect the incumbent to quarantine the agent, block its execution, or throttle it. Supply your security team with:

• the install directory (/usr/local/cyberarmor or %PROGRAMFILES%\CyberArmor)
• the service name (ai.cyberarmor.endpoint)
• the process name (cyberarmor-agent)

Two endpoint agents on one machine is a supported configuration, but not an automatic one.

The local proxy is a separate decision

The endpoint agent and the local proxy are different installs with very different footprints.

The proxy provides in-line AI Trust Gate enforcement, and to do so it changes the system proxy settings and installs a CA certificate. In a regulated environment that is a security-review item and often a change-control ticket. It has also historically interfered with captive-portal sign-in on public wifi — an included watchdog handles that, but it is a moving part.

The agent delivers endpoint detection, patch management, A-BOM, and shadow-AI discovery without it. Deploy the agent first, and treat the proxy as a deliberate second phase.

Fleet rollout

Two things worth planning for a large deployment:

First-sync bandwidth. Each endpoint downloads the known-good corpus once — currently ~2.2 GB. Across 800 endpoints that is roughly 1.76 TB. Stage the rollout rather than enrolling a whole site on one morning. Subsequent updates are deltas and are small.

Exclusion approval lead time. See above. It is usually the longest pole, and it is entirely a paperwork problem, so start it first.

Uninstall

sudo python3 /usr/local/cyberarmor/installer.py uninstall

Add --purge to remove configuration and logs as well. On macOS the per-user clipboard helper, if installed, is removed separately — the uninstaller prints the exact commands.

Troubleshooting

Symptom	Cause
Endpoint never appears in Endpoints	Wrong --tenant-id, or control-plane egress blocked
Monitoring: Degraded	Full Disk Access not granted — run disk_access.py
No file events despite Monitoring: OK	Run the --canary check; readability and event delivery are separate grants
Corpus version stays at 0	Object-storage egress blocked, or no manifest published yet
python3 -m venv fails on Ubuntu	Install python3-venv

See also Endpoint Agent, Endpoint Detection, and Patch Management.