Hodei-Shield Agent — beta tester quick start¶
One page: from nothing to an enrolled, reporting machine. Beta participants may install the agent from 2026-11-02. Install the 2.23.2 release.
How much each part has been tested¶
Read this before you start, because the three systems are not in the same state.
The word MEASURED is used only when Hodeitek holds the evidence of a
run, and it names where. NOT RUN means nobody has run it yet and it is written
from the packaging.
| System | State |
|---|---|
| Windows | The full path was run on clean Windows 11 and Windows Server 2022 hosts with 2.12.4 (2026-10-11 and 2026-10-12), and the install and enrollment of the published, signed 2.13.0 set on a fresh Windows 11 host (2026-10-14). MEASURED 2026-11-17 on Windows 11 with the 2.22.0 MSI (Authenticode signature valid, "Hodeitek S.L."): install, enrollment, a first report and uninstall passed, and the self-update decision went from apply_unsupported to opt_out; an actual update and TELEMETRY=off were not run, and this was 2.22.0, not 2.23.0. The commands, and the measured result for each, are in the Windows beta guide: follow that guide for the exact blocks |
| Linux | The download check was run (MEASURED 2026-10-11, see Verify the agent download). An enrollment of the published 2.0.0 binary on a Linux host was done earlier. MEASURED 2026-11-17 on Debian 13 (virtual machine, clean snapshot) with the 2.22.0 release from downloads.hodeishield.com, following this guide as written: download, signature and checksum verification, install, enrollment against the production console, a first report submitted (outcome ok), the self-update decision shown in the console (enabled, then opt_out with the local marker) and uninstall all passed. NOT RUN: an actual update (there was no newer version) and TELEMETRY=off. This was measured with 2.22.0, not 2.23.0 |
| macOS | Nothing in this page has been run on a Mac. Every macOS step is NOT RUN and comes from the packaging. No successful macOS enrollment has been recorded |
If you install on Linux or macOS you are among the first to follow these paths from start to finish. If a step does not behave as written, stop and tell us (see Help); do not improvise on the enrollment step, which uses up your token.
The full per-OS guides are Linux, Windows and macOS.
1. Prerequisites¶
You need, for each machine:
- Administrator rights (
root/ Administrator) and outbound HTTPS to your platform URL and todownloads.hodeishield.com. - One enrollment token, created just before you use it. It works once: two machines need two tokens. Who creates it: the administrator of your organisation creates it in the console. If you take part through an MSSP (a managed security provider), the MSSP's administrator creates it. You do not create it yourself, and nobody should send it to you through a channel others can read.
- An agent id, chosen now: letters, digits and
. _ : -, starting with a letter or digit. It becomes the machine's permanent name in the console. - The platform URL shown in the console (
https://…). For the beta it ishttps://app.hodeishield.com(see the Windows beta guide).
| OS | Supported | Also needed to verify the download |
|---|---|---|
| Linux | x86_64 with systemd | OpenSSL 3 (openssl version) |
| Windows | x64, 2.13.0 or later |
OpenSSL 3 (Git for Windows ships one) and PowerShell |
| macOS | 13 or later, Apple Silicon or Intel | OpenSSL 3 (brew install openssl@3); the system openssl is LibreSSL and cannot do the check |
No Visual C++ redistributable is required from 2.13.0 on.
On Windows the status window and tray work without a graphics driver (VMs, VDI, servers): the window uses DirectX 12 and falls back to Windows' built-in WARP software renderer; the agent runs and reports regardless. MEASURED 2026-10-12 (as recorded in the Windows beta guide).
2. Before the first start: what it sends, and the telemetry switch¶
Read this before the agent runs for the first time. Two things leave the machine:
- The security check results, to your organisation's platform: which checks ran and whether each passed, a few allowed facts, the host name, the routable IP addresses and the operating system version. Never files, documents, passwords, keys or tokens. The full list, with where each claim comes from, is in what-leaves-the-machine.md (en español). The privacy notice of the console is at https://app.hodeishield.com/privacy.
- Error reports (telemetry). In the beta, the official builds can report errors and crashes, through your console (which forwards them to our error-tracking service), and only while the console has sent a signed "yes" for your tenant: off by default. Today no console offers them yet, so an agent of version 2.23.0 or later sends none. This is declared here and in What leaves your machine. It contains no personal data by design (no host name, IP address, user name or check results; free text is scrubbed), and a healthy agent sends nothing. You can also force it off, per machine, with one file.
To force it off, create this marker file before the first start. Its contents are ignored; its presence is what counts. It survives upgrades.
| OS | When | Command |
|---|---|---|
| Linux | After step 4 creates /etc/hodei-shield, before step 6 starts the service |
sudo mkdir -p /etc/hodei-shield && sudo touch /etc/hodei-shield/telemetry-off |
| macOS | Before installing the .pkg (the package starts the service by itself) |
sudo mkdir -p /etc/hodei-shield && sudo touch /etc/hodei-shield/telemetry-off |
| Windows | Right after the .msi installs, before step 5 (the installer creates and protects the folder itself, so do not create it earlier) |
New-Item -ItemType File -Force "$env:ProgramData\Hodei-Shield\telemetry-off" \| Out-Null; Restart-Service hodei-shield (elevated PowerShell) |
NOT RUN for Linux and macOS. For Windows the same command is recorded as
measured in the Windows beta guide (2026-10-12).
The marker is read when each process starts: restart the service after creating
or removing it. To check, run hodei-shield version; its second line says
telemetry for this process's environment: off (opt-out file …). An
environment variable (HODEI_SENTRY_DSN=off) also works, but the marker file is
the one to use for a service. Details and limits:
What leaves your machine. To have the installer create the marker, and for hosts behind a proxy, see Install with error reports off and Behind a proxy.
If the machine will also show the status window, read What leaves your machine too: it says what a person at the screen sees and who controls it.
What a person at the screen may see. If your organisation switches desktop notices to Active, the status window program raises a short notice, once, when a check starts failing: "Something to review / Open the HodeiShield window to see it." (Spanish: "Hay algo que revisar / Abre la ventana de HodeiShield para verlo."). It never names the check, the machine or the severity, and nothing about it is sent to the platform. Your organisation decides from the console (Off, Discreet, Active); with no decision the default is Discreet (no notice). Unmeasured: this has not been run on a real notification service on any OS; read it as intended behaviour.
3. Download and verify¶
Download the installer, SHA256SUMS and SHA256SUMS.sig for the 2.23.0
release from https://downloads.hodeishield.com/agent/2.23.2/
(set V=2.23.2; the version field of https://downloads.hodeishield.com/agent/stable/agent-update-manifest.json names the current stable version),
then verify the signature on SHA256SUMS with the Hodei-Shield release key
before installing anything. The key, its fingerprint and the exact commands
for Linux, macOS and Windows are in
Verify the agent download, "What is signed, and how to check it".
The Linux check is MEASURED; the macOS check is NOT RUN; the Windows
check is run inside the install step of
the Windows beta guide.
Do not continue if you do not see Signature Verified Successfully and an OK
for your file.
Key custody: releases are signed with a dedicated, verifiable key (details).
4. Install¶
Linux, from the extracted tarball (NOT RUN end to end; the commands are the
ones in the Linux beta guide):
sudo useradd --system --no-create-home --shell /usr/sbin/nologin hodei-shield
sudo install -d -o root -g root -m 0755 /usr/lib/hodeishield /usr/lib/hodeishield/bin
sudo install -o root -g root -m 0755 hodei-shield /usr/lib/hodeishield/bin/hodei-shield
sudo ln -sfn /usr/lib/hodeishield/bin/hodei-shield /usr/local/bin/hodei-shield # for typing only
sudo install -o root -g root -m 0644 hodei-shield.service /etc/systemd/system/
sudo install -d -o root -g root -m 0755 /etc/hodei-shield
sudo install -o root -g hodei-shield -m 0640 platform-ca.pem /etc/hodei-shield/
sudo install -d -o hodei-shield -g hodei-shield -m 0700 /var/lib/hodei-shield
Windows: follow step 2 ("Verify and install") of
the Windows beta guide
(it checks the publisher, the release signature and the checksum, and installs
only if all three pass). It is recorded as measured with the published, signed
2.13.0 set (2026-10-14). Do not run a bare msiexec by itself.
macOS (NOT RUN), after the verification in section 3:
The Windows and macOS packages create the service account and state folder
themselves. Updates later: Linux applies them itself, only when the console's signed
policy approves the release; Windows (stable) and macOS have no working applier, so you
install the new .msi or .pkg by hand, with no new token (see the guides). Never put the token on an installer command line.
5. Configuration file¶
The file has two lines. Use your platform URL; the state folder is the one below for your OS.
| OS | File | state_dir |
|---|---|---|
| Linux | /var/lib/hodei-shield/hodei-shield.toml |
/var/lib/hodei-shield |
| Windows | C:\Program Files\Hodei-Shield\Agent\hodei-shield.toml |
C:\ProgramData\Hodei-Shield\state |
| macOS | /var/lib/hodei-shield/hodei-shield.toml |
/var/lib/hodei-shield |
NOT RUN for Linux and macOS. On Windows write the state_dir value in single
quotes ('C:\ProgramData\Hodei-Shield\state') so the backslashes are literal;
the Windows block is recorded as measured in
the Windows beta guide (2026-10-12).
6. Enroll¶
Never type the token on a command line: it would be visible to every user on the
machine and stay in your shell history. Save it in a file only an administrator
can read, pipe it in with --token-stdin, and delete it.
Linux (NOT RUN; enroll must be run once per machine, and the service is
started only afterwards):
sudo sh -c 'umask 077; cat > /root/hodei-token' # paste the token, press Ctrl-D
sudo sh -c 'cat /root/hodei-token' | sudo -u hodei-shield env \
HODEI_PLATFORM_URL="https://<platform host>" \
HODEI_STATE_DIR=/var/lib/hodei-shield \
/usr/lib/hodeishield/bin/hodei-shield enroll --token-stdin --agent-id '<this machine id>'
sudo shred -u /root/hodei-token
sudo systemctl enable --now hodei-shield
Windows: follow step 3 ("Configure and enroll") of
the Windows beta guide. It is recorded
as measured on 2026-10-12 (the token is typed at a prompt, never on a command
line). Run enroll from the agent folder (C:\Program Files\Hodei-Shield\Agent).
macOS (NOT RUN):
sudo sh -c 'umask 077; cat > /var/root/hodei-token' # paste the token, press Ctrl-D
sudo sh -c 'cat /var/root/hodei-token' | sudo -u _hodeishield env \
HODEI_PLATFORM_URL="https://<platform host>" \
HODEI_STATE_DIR=/var/lib/hodei-shield \
/usr/local/bin/hodei-shield enroll --token-stdin --agent-id '<this machine id>'
sudo rm -P /var/root/hodei-token
sudo launchctl kickstart -k system/com.hodeitek.hodei-shield
Success prints enrolled: producer=endpoint_agent:<id> public_key_id=… tenant_id=….
If it fails, do not retry with the same token: a rejected token never says why
(unknown, used, expired and revoked look the same). Ask your administrator for a
new token and see Enrollment token rejected.
If you see a certificate or TLS error. Do not add a certificate to the
operating system's trust store and do not turn verification off: the agent does
not use the system store. It trusts only the platform CA bundle that the
installer put in place: /etc/hodei-shield/platform-ca.pem on Linux and macOS,
C:\ProgramData\Hodei-Shield\state\platform-ca.pem on Windows. If that file is
missing, enroll names the path and stops. Send the output of hodei-shield diagnose to your
administrator. A platform [FAIL] line with a TLS error in
hodei-shield diagnose has the same cause (TLS or certificate error).
Other failures you can meet in a beta, and the step for each (the exact messages, the cause and the fix are in troubleshooting.md):
| What you see | Step |
|---|---|
the platform rejected this enrollment token …, enrollment token is malformed …, enrollment rate-limited … |
Enrollment token rejected, malformed or rate-limited |
this tenant already has a producer with this agent id |
Agent id already in use |
diagnose says clock [FAIL] |
Clock skew |
The service will not start, restarts in a loop, or run exits 75 |
Service does not start, restarts in a loop or exits 75 |
offline queue is full … |
Offline queue full or backlogged |
An update is refused: version_not_approved, identity_unpinned, manifest_replayed |
Update refused |
7. Check that it is running¶
| OS | Service running | Identity loads (exit 0; Windows also prints INFO lines) |
|---|---|---|
| Linux | systemctl is-active hodei-shield says active |
sudo -u hodei-shield sh -c 'cd /var/lib/hodei-shield && exec /usr/lib/hodeishield/bin/hodei-shield self-test' |
| Windows | Get-Service hodei-shield says Running |
from the agent folder: & '.\hodei-shield.exe' self-test |
| macOS | sudo launchctl print system/com.hodeitek.hodei-shield \| head |
sudo -u _hodeishield sh -c 'cd /var/lib/hodei-shield && exec /usr/local/bin/hodei-shield self-test' |
Linux and macOS: NOT RUN. Windows: recorded as measured in
Windows beta guide.
The machine appears in the console after its first cycle (on Windows, the first
submission was accepted about 2.5 minutes after the restart).
8. Uninstall and full purge¶
Two things, in this order: stop and remove the program, then decide whether to destroy what it left behind. Uninstalling keeps the machine's private key, so a reinstall does not need a new enrollment. Deleting the state folder is irreversible: the machine can never report again under the same identity.
Revoke the machine in the console first. Your organisation's administrator
(role platform_admin, org_admin or tenant_admin) revokes the producer
there (the producer is named endpoint_agent:<agent id>); this stops the
platform from accepting that key and frees the name. In the console (v2.44.x):
open the Endpoints menu, open the endpoint's detail page, press Revoke
enrolment and confirm in the Revoke this enrolment dialog. The inverse is
Reinstate enrolment.
Revoking does not by itself delete the observations already received: the
platform keeps a revoked
producer's row and its observations (a platform behaviour that the agent
could not observe). Retention and deletion of data already received
are for the privacy notice and your administrator, not for this agent.
All the commands below are NOT RUN on a real host unless a line says
otherwise.
Linux¶
Remove the program (see also Uninstall in the Linux beta guide):
sudo systemctl disable --now hodei-shield
sudo rm -f /etc/systemd/system/hodei-shield.service
sudo systemctl daemon-reload
sudo rm -f /usr/lib/hodeishield/bin/hodei-shield /usr/lib/hodeishield/bin/hodei-shield-gui
sudo rmdir /usr/lib/hodeishield/bin /usr/lib/hodeishield
# the convenience symlinks, or the real files of a host installed before the /usr/lib/hodeishield layout
sudo rm -f /usr/local/bin/hodei-shield /usr/local/bin/hodei-shield-gui
# Before userdel frees the service uid, hand the kept key material to root:
# an account created later can be given that uid and must not own it.
# The find refuses a file with a second hard link: under fs.protected_hardlinks=0
# the service account could plant one to a system file for chown to re-own.
# pkill/pgrep and the non-recursive chown/chmod come first, so no process of that
# uid can add one between the find and the chown -R (NOT RUN).
sudo pkill -KILL -u hodei-shield; ! pgrep -u hodei-shield \
&& sudo chown root:root /var/lib/hodei-shield /etc/hodei-shield && sudo chmod 0700 /var/lib/hodei-shield \
&& l="$(sudo find /var/lib/hodei-shield /etc/hodei-shield -xdev ! -type d -links +1 -print -quit)" && [ -z "$l" ] \
&& sudo chown -R root:root /var/lib/hodei-shield /etc/hodei-shield \
&& sudo chmod -R u=rwX,go= /var/lib/hodei-shield && sudo userdel hodei-shield
What this leaves:
| Leftover | What it is |
|---|---|
/var/lib/hodei-shield |
the private key, the encrypted offline queue, hodei-shield.toml, state files; owned by root, 0700/0600, after the step above |
/etc/hodei-shield |
the CA bundle and telemetry-off if you created it; owned by root |
| the journal | log lines in journalctl -u hodei-shield; the agent writes no log file on Linux. They age out with the journal's own retention |
/usr/share/applications/com.hodeitek.hodei-shield.desktop and /usr/share/icons/hicolor/*/apps/com.hodeitek.hodei-shield.png |
only if you installed the desktop window |
~/.config/hodei-shield (or $XDG_CONFIG_HOME/hodei-shield) of each person who ran the window |
the window's own preferences and notice record |
Full purge (irreversible; run it only after you have revoked the machine):
sudo rm -rf /var/lib/hodei-shield /etc/hodei-shield
sudo rm -f /usr/share/applications/com.hodeitek.hodei-shield.desktop
sudo rm -f /usr/share/icons/hicolor/*/apps/com.hodeitek.hodei-shield.png
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/hodei-shield" # as each user who ran the window
macOS¶
The .pkg ships an uninstaller, /usr/local/libexec/hodei-shield/uninstall.sh
(NOT RUN on a Mac; it is written from the packaging). Run it as root. By default it keeps
/var/lib/hodei-shield and /var/log/hodei-shield; --purge deletes both, after refusing a
symlink, a foreign owner or a mode other than 0700 (it checks everything before deleting anything):
sudo /usr/local/libexec/hodei-shield/uninstall.sh # keeps the key and the logs
sudo /usr/local/libexec/hodei-shield/uninstall.sh --purge # also deletes key, queue, config, logs
It stops the three daemons and removes the binary, the update helper, the app, the CA bundle,
the licence notices, the status folder, the _hodeishield account (only if the package created
it) and the receipt. What is left (without --purge): /var/lib/hodei-shield,
/var/log/hodei-shield, and /etc/hodei-shield if it still holds telemetry-off (or a
self-update.disabled you created; on macOS that file is made with -g wheel, because there is
no root group). Before it deletes the account, a plain uninstall hands the kept folders to
root (NOT RUN on a Mac); a reinstall hands the state back to the new account.
macOS logs are rotated by the agent itself (10 MiB, 5 archives .0–.4, files 0640).
No newsyslog rule is installed; upgrading removes any rule an earlier build left.
For a .pkg older than 2.19.0 (no uninstaller), remove what it laid down by hand :
sudo launchctl unload -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist
sudo launchctl unload -w /Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist
sudo rm /Library/LaunchDaemons/com.hodeitek.hodei-shield.plist \
/Library/LaunchDaemons/com.hodeitek.hodei-shield.runtime-dir.plist
sudo launchctl bootout system/com.hodeitek.hodei-shield.update # root update job (2.16.0+); a no-op if it is not loaded
sudo rm -f /Library/LaunchDaemons/com.hodeitek.hodei-shield.update.plist /Library/PrivilegedHelperTools/com.hodeitek.hodei-shield.update
sudo rm -f /usr/local/bin/hodei-shield
sudo rm -rf /Applications/Hodei-Shield.app
# NOT RUN on a Mac. Before dscl frees the service uid, hand the kept key
# material to root: an account created later can be given that uid. The find
# refuses a file with a second hard link (macOS lets the service account link a
# system file for chown to re-own); pkill/pgrep and the non-recursive chown/chmod
# first, so no process of that uid can add one between the find and the chown -R.
# Any failed step stops the chain and keeps the
# account. No /etc/hodei-shield? Drop it from both the find and the chown.
# boot out the account's per-user launchd domain first, or launchd respawns
# its distnoted agent after pkill and pgrep never comes back empty.
sudo launchctl bootout user/"$(id -u _hodeishield)" 2>/dev/null
sudo pkill -KILL -u _hodeishield; ! pgrep -u _hodeishield \
&& sudo chown root:wheel /var/lib/hodei-shield /etc/hodei-shield && sudo chmod 0700 /var/lib/hodei-shield \
&& l="$(sudo find /var/lib/hodei-shield /etc/hodei-shield -xdev ! -type d -links +1 -print -quit)" && [ -z "$l" ] \
&& sudo chown -R root:wheel /var/lib/hodei-shield /etc/hodei-shield \
&& sudo chmod -R u=rwX,go= /var/lib/hodei-shield && sudo dscl . -delete /Users/_hodeishield \
&& sudo dscl . -delete /Groups/_hodeishield
sudo pkgutil --forget com.hodeitek.hodei-shield
What this leaves:
| Leftover | What it is |
|---|---|
/var/lib/hodei-shield |
the private key, the encrypted offline queue, hodei-shield.toml |
/etc/hodei-shield |
the CA bundle and telemetry-off if you created it |
/var/log/hodei-shield |
the agent's logs (hodei-shield.log, .err.log) |
/usr/local/share/doc/hodei-shield |
the third-party licence notices |
/var/run/hodei-shield |
the status file; macOS clears /var/run on restart |
~/Library/Application Support/Hodei-Shield of each person who ran the window |
the window's own preferences and notice record |
Full purge (irreversible; after revoking; also remove the files above):
sudo rm -rf /var/lib/hodei-shield /etc/hodei-shield /var/log/hodei-shield \
/usr/local/share/doc/hodei-shield /var/run/hodei-shield
rm -rf "$HOME/Library/Application Support/Hodei-Shield" # as each user who ran the window
Delete the account and the state together or not at all: a state folder kept after the account is deleted is owned by a numeric id that a future account may not get.
Windows¶
The uninstall of the .msi is recorded as measured in
the Windows beta guide
(2026-10-12): it removes the service and the program, and keeps the state on
purpose.
# elevated PowerShell; point it at the .msi you kept
$msi = (Resolve-Path '<folder where you downloaded it>\hodei-shield-<version>-x86_64.msi').Path
(Start-Process msiexec.exe -ArgumentList '/x', "`"$msi`"", '/qn' -Wait -PassThru).ExitCode
What this leaves:
| Leftover | What it is |
|---|---|
C:\Program Files\Hodei-Shield\Agent\hodei-shield.toml and Agent\logs\*.log |
the configuration and the service logs |
C:\ProgramData\Hodei-Shield\state\ |
the private key, the offline queue, platform-ca.pem, agent.lock |
C:\ProgramData\Hodei-Shield\telemetry-off |
only if you created it |
C:\ProgramData\Hodei-Shield\THIRD-PARTY-NOTICES.txt |
licence notices |
%APPDATA%\Hodei-Shield of each person who ran the window |
the window's own preferences and notice record |
Full purge (irreversible; after revoking; NOT RUN). The state folder is
protected so that only Administrators, SYSTEM and the service account can open
it, and a protected folder can refuse deletion even to an elevated prompt until
you take ownership. The guard stops if the folder was replaced by a link:
foreach ($p in 'C:\ProgramData\Hodei-Shield', 'C:\Program Files\Hodei-Shield') {
if (Test-Path -LiteralPath $p) {
if ((Get-Item -LiteralPath $p -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) { throw "$p is a link: stop and ask for help" }
Remove-Item -LiteralPath $p -Recurse -Force
}
}
Remove-Item -LiteralPath "$env:APPDATA\Hodei-Shield" -Recurse -Force -ErrorAction SilentlyContinue # per user
If Remove-Item reports access denied on state, take ownership of that one
folder first (takeown /f 'C:\ProgramData\Hodei-Shield\state' /r /d y and then
icacls 'C:\ProgramData\Hodei-Shield\state' /grant Administrators:F /t), and
run the purge again. These two lines are not covered by any recorded run.
Help¶
- Logs:
- Linux:
journalctl -u hodei-shield -n 100 --no-pager - Windows:
C:\Program Files\Hodei-Shield\Agent\logs\(newest file; read it from an elevated prompt) - macOS:
/var/log/hodei-shield/hodei-shield.logand.err.log - Start with troubleshooting.md.
hodei-shield diagnoseproduces a redacted support bundle to attach to a ticket.- To ask for help or report a problem: write to info@hodeitek.com, or use the "Beta" button in the console. We answer within one working day. That is a commitment to answer, not to resolve.
- For a token, or to revoke a machine: your organisation's administrator
(or your MSSP's administrator) does it in the console. To revoke: Endpoints
menu, the endpoint's detail page, Revoke enrolment (console v2.44.x; roles
platform_admin,org_admin,tenant_admin).