Skip to content

Install the Agent

The KVM Fleet agent is a single static Go binary (~5 MB) that runs on any Linux-based KVM device.

One-line install

curl -sSL https://app.kvmfleet.io/install | sh -s -- --token <enrollment-token>

Options

Flag Description
--token <token> Enrollment token from the dashboard (required)
--name <name> Device name (optional, defaults to hostname)
--tags <t1,t2> Comma-separated tags (optional)
--api <url> Platform URL (default: https://app.kvmfleet.io)

Environment variables

You can also pass configuration via environment variables:

KVMFLEET_TOKEN=ekvent_xxx curl -sSL https://app.kvmfleet.io/install | sh

What the install script does

  1. Detects architecture — armv7l (ARMv7), aarch64 (ARM64), or x86_64
  2. Detects device type — checks for known KVM software (kvmd, JetKVM config)
  3. Downloads the binary — from https://app.kvmfleet.io/downloads/
  4. Sets up the service — systemd unit or BusyBox init script
  5. Starts the agent — enrolls and connects to the platform

Install paths

Device type Binary location State file Persists across firmware updates
JetKVM /userdata/kvmfleet/agent /userdata/kvmfleet/state.json Yes
PiKVM /usr/local/bin/kvmfleet-agent /var/lib/kvmfleet/state.json Depends on OS update method
Generic Linux /usr/local/bin/kvmfleet-agent /var/lib/kvmfleet/state.json Yes

Manual install

If you prefer not to use the install script:

# Download the binary for your architecture
wget https://app.kvmfleet.io/downloads/kvmfleet-agent.linux-arm64
chmod +x kvmfleet-agent.linux-arm64
mv kvmfleet-agent.linux-arm64 /usr/local/bin/kvmfleet-agent

# Write the enrollment token
mkdir -p /var/lib/kvmfleet
echo 'ekvent_your_token_here' > /var/lib/kvmfleet/enrollment.token

# Run
KVMFLEET_API=https://app.kvmfleet.io \
KVMFLEET_TOKEN_FILE=/var/lib/kvmfleet/enrollment.token \
EUROKVM_STATE=/var/lib/kvmfleet/state.json \
  /usr/local/bin/kvmfleet-agent run

Build from source

git clone https://github.com/KVM Fleet/agent.git
cd agent
go build -trimpath -o kvmfleet-agent ./

Cross-compile:

# ARM64 (PiKVM, Raspberry Pi)
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -o kvmfleet-agent.linux-arm64 ./

# ARMv7 (JetKVM)
GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 go build -trimpath -o kvmfleet-agent.linux-arm ./

Verify enrollment

After install, the agent creates a state file containing the device ID and auth token. Check it's enrolled:

cat /var/lib/kvmfleet/state.json

The device should appear in the dashboard within seconds.

Uninstall

systemctl stop kvmfleet-agent
systemctl disable kvmfleet-agent
rm /etc/systemd/system/kvmfleet-agent.service
rm /usr/local/bin/kvmfleet-agent
rm -rf /var/lib/kvmfleet
systemctl daemon-reload

/userdata/kvmfleet/init.sh stop
rm /etc/init.d/S99kvmfleet
rm -rf /userdata/kvmfleet