Agent Auto-Update¶

Agents can keep themselves up to date automatically. Instead of manually re-downloading the binary and replacing it on every host, an auto-updating agent downloads new versions, verifies and installs them while idle, and rolls back on its own if something goes wrong. This page explains how it works, how to install an auto-updating agent, and the administrator controls that govern the rollout.

How automatic updates work¶

Idle-only: An update is applied only when the agent is idle. If the agent is running a job, it finishes its current work first — a running job is never interrupted to update.
Verified and reversible: Each update is checksum verified, the current binary is backed up first, and if the new version fails to come back online the agent automatically rolls back to the previous binary and keeps running.
Gradual rollout: Updates roll out across your fleet gradually, with a configurable limit on how many agents update at once, so the server and network aren't overwhelmed.
Failures are visible: If an update fails, the agent keeps running the previous version, and the failure is surfaced on the Agent Management page with a manual retry option.

The launcher¶

Auto-updating agents run under a small companion program called the launcher. The launcher supervises the agent process and performs the download, binary swap, and restart while the agent is stopped — that brief, supervised stop is what makes a safe self-update possible (a process can't reliably replace its own running binary).

By default the launcher installs as a per-user service and does not require root or Administrator. It runs as the user who installed it, out of that user's own folder — just like a normally-run agent:

Platform	Per-user service
Linux	a user systemd service
macOS	a per-user login agent (not tested)
Windows	a per-user logon task (not tested)

For servers that must start the agent before any user logs in, install a system-wide service with the --system flag, which requires sudo (Linux/macOS) or Administrator (Windows).

You can still run a standalone agent

Using the launcher is optional. You can continue to run a standalone agent and manage updates yourself if you prefer.

Installing an auto-updating agent¶

The easiest path is the Install an Agent panel on the Agent Management page:

In the Admin UI, open Agents and use the Install an Agent panel.
Choose your operating system. A dialog walks you through the rest.
Pick the CPU architecture, pick or generate a claim code, and confirm the server address (pre-filled from the address you're already using).
Copy one of the ready-made commands. Each platform offers three options:
Install as a service (uses the launcher — recommended for auto-updates)
Run in a terminal
Download the binary directly

The service option produces a launcher install command equivalent to:

# Per-user service (no root/Administrator needed)
krakenhashes-launcher install --host SERVER:31337 --claim YOUR_CLAIM_CODE

# System-wide service (starts before login; needs sudo/Administrator)
krakenhashes-launcher install --system --host SERVER:31337 --claim YOUR_CLAIM_CODE

Optional --config-dir and --data-dir flags relocate the configuration/credentials and the binaries/wordlists/rules/hashlists directories.

Standalone agents (without the launcher)¶

A standalone agent — one started directly rather than through the launcher — keeps working exactly as before and does not auto-update. You update it manually by replacing its binary. This is a valid choice if you want full control over when each host changes versions. See Installation for running the agent directly.

Uninstalling¶

The launcher can cleanly remove its own service:

# Remove the service (leaves binaries, config, and data in place)
krakenhashes-launcher uninstall            # add --system if it was a system install

# Full removal: also delete binaries, configuration (including credentials), and downloaded data
krakenhashes-launcher uninstall --purge    # add --system for a system install

--purge deletes credentials and data

The --purge flag removes the installed binaries, the configuration (including the agent's credentials), and downloaded data for a complete removal. Use it only when you intend to fully decommission the agent on that host.

Administrator controls¶