Installation

One binary per server. Sixty seconds from download to first snapshot.

Before you install 1. Create your account at kefal.dev/app — 10 seconds, no credit card, 7-day free trial.
2. In the dashboard, open Settings → API Keys → Generate and copy the kfl_… key. The agent prompts for it on first run.
3. Verify the download against our published checksums before running it as root.

Verify what you downloaded

The agent runs as root on your servers, so check it is the file we published before you run it. Every release is listed in SHA256SUMS, and the binary served here is byte-for-byte the one running on our own infrastructure.

curl -L -O https://kefal.dev/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS

Expect kefal-agent-linux-amd64: OK. On macOS the command is shasum -a 256 -c SHA256SUMS --ignore-missing; on Windows PowerShell, Get-FileHash .\kefal-agent-windows-amd64.exe -Algorithm SHA256 and compare the line by eye.

If the check fails Do not run the binary. Delete it, download it again, and if it fails a second time write to us before going any further — a mismatch means the file you have is not the file we shipped.

Linux (amd64 — Intel/AMD 64-bit)

The most common target: Ubuntu, Debian, RHEL, Rocky, AlmaLinux, Amazon Linux 2023. Works on any x86_64 distribution with glibc.

curl -L -o kefal-agent https://kefal.dev/download/kefal-agent-linux-amd64
chmod +x kefal-agent
sudo ./kefal-agent

The agent prompts for an API key (kfl_…, generated from your dashboard at kefal.dev/app → Settings → API Keys). On successful enrollment it writes its config to /etc/kefal/agent.conf with mode 0600 and begins sending snapshots every 60 seconds.

Run as a service (recommended)

By default the agent runs in the foreground. For production, wrap it in a systemd unit so it auto-starts at boot:

sudo tee /etc/systemd/system/kefal-agent.service >/dev/null <<'EOF'
[Unit]
Description=Kefal defense agent
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/kefal-agent
Restart=on-failure
RestartSec=10s
User=root

[Install]
WantedBy=multi-user.target
EOF

sudo mv kefal-agent /usr/local/bin/
sudo systemctl daemon-reload
sudo systemctl enable --now kefal-agent
sudo systemctl status kefal-agent

Linux (ARM64 — Raspberry Pi 4/5, AWS Graviton, Ampere, Apple Silicon Docker)

curl -L -o kefal-agent https://kefal.dev/download/kefal-agent-linux-arm64
chmod +x kefal-agent
sudo ./kefal-agent

Same interactive enrollment as above. The ARM64 binary is statically linked and runs on any aarch64 Linux system.

macOS (Apple Silicon — M1/M2/M3/M4)

curl -L -o kefal-agent https://kefal.dev/download/kefal-agent-darwin-arm64
chmod +x kefal-agent
xattr -d com.apple.quarantine kefal-agent  # bypass Gatekeeper for unsigned binary
sudo ./kefal-agent

The agent stores its config at /etc/kefal/agent.conf. The xattr step is required because the binary is not yet notarized — we plan to ship a signed/notarized build in a future release.

macOS (Intel — pre-2020 Macs)

curl -L -o kefal-agent https://kefal.dev/download/kefal-agent-darwin-amd64
chmod +x kefal-agent
xattr -d com.apple.quarantine kefal-agent
sudo ./kefal-agent

Windows (x64)

Open PowerShell as Administrator and run:

Invoke-WebRequest -Uri "https://kefal.dev/download/kefal-agent-windows-amd64.exe" `
                  -OutFile "kefal-agent.exe"
.\kefal-agent.exe

You'll be prompted for your Kefal API key. The agent stores its config under %ProgramData%\Kefal\agent.conf.

Run as a Windows service

Use Task Scheduler to run the agent at boot:

schtasks /create /tn "Kefal Agent" `
         /tr "C:\Program Files\Kefal\kefal-agent.exe" `
         /sc onstart /ru SYSTEM /rl HIGHEST

Verify the agent is reporting

Within 90 seconds of the first run, your host should appear in the dashboard. To verify from the server itself:

# Check the agent process is alive
ps aux | grep kefal-agent    # Linux
Get-Process kefal-agent      # Windows PowerShell

# Check snapshots are being sent (look for "ingest ok" lines every ~60s)
journalctl -u kefal-agent -f                      # systemd
Get-EventLog -LogName Application -Source Kefal   # Windows

Then open the dashboard at kefal.dev/app/. Within a minute or two you should see the host as a node in the Graph view.

Troubleshooting

Enrollment fails with "API key was rejected"

The key is malformed or revoked. Generate a fresh one at kefal.dev/app → Settings → API Keys.
You pasted a session token instead — check the prefix is kfl_ and the length is 52 chars.
Your trial expired. Check status in the dashboard under Billing.

Agent runs but nothing shows up in the dashboard

Check the host can reach kefal.dev: curl -I https://kefal.dev must return 200.
Firewall may block outbound HTTPS. Whitelist destination kefal.dev on port 443/tcp.
Check agent logs for 402 Payment Required — that means the trial expired.

"Permission denied" when the agent reads process info

The agent needs to run as root (Linux) or SYSTEM (Windows) to see every process. Without root it only sees the invoking user's processes, which is insufficient for detection.

Uninstall

# Linux
sudo systemctl stop kefal-agent
sudo systemctl disable kefal-agent
sudo rm -f /etc/systemd/system/kefal-agent.service /usr/local/bin/kefal-agent
sudo rm -rf /etc/kefal/

# Windows
schtasks /delete /tn "Kefal Agent" /f
Remove-Item -Recurse -Force "C:\Program Files\Kefal"
Remove-Item -Recurse -Force "C:\ProgramData\Kefal"

Also remove the agent from your account at kefal.dev/app/ under Settings → Agents.