Introduction
The Level agent is a lightweight background service that checks in with your account and makes remote monitoring, automation, and management available for a Linux device. Install is a single command run as root or with sudo.
⚙️ PREREQUISITES
A Level account with permission to add devices
Root access or sudo on the target device
A supported Linux distribution running systemd
Required packages:
curl,bash,ca-certificates,sudo,dbus(or a UUID in/etc/machine-id)
🎬 VIDEO
Linux Install
Click Add new device in the top-right corner of the Device Listing page. In the OS selector, choose Linux.
Selecting a Device Group (Optional)
Select a device group before copying your install command. The install key updates to include the group ID, so the device lands in the right group on first check-in.
If you skip this, the device lands in Ungrouped. You can move it afterward.
The Install Key
Every Linux install method uses an install key, a short token visible in the modal that links new devices to your Level account. It's scoped narrowly: if exposed, it can't access your account, existing devices, or the Level API. The only risk is that someone could use it to add devices to your account.
If you believe your install key has been compromised, contact Level support to rotate it.
ℹ️ NOTE: The install key reflects your group selection in real time. Without a group selected, it contains just your account identifier. Select a group and the group's ID is appended.
Install Methods
The modal has two tabs for Linux.
One-Line Command
A bash one-liner that downloads and installs the agent. This is the standard method for most Linux deployments and handles architecture detection automatically.
In the modal, select the One-line command tab.
Optionally select a device group.
Copy the generated command.
On the target device, open a terminal.
Run the command. If you're not already root, the command includes
sudo: you'll be prompted for your password.
The device shows up in your Device Listing within 5–10 seconds of the install completing.
Installer
Downloads an architecture-specific binary and installs it via command line. Use this when you need to specify the architecture explicitly or prefer a manual install process.
In the modal, select the Installer tab.
Select your architecture from the dropdown: x64 or ARM.
Optionally select a device group.
Click Download installer to download the binary.
Copy the install command shown in the modal.
On the target device, run the copied command with elevated permissions.
The command makes the binary executable and runs the install, registering the device with your account using the embedded install key.
Custom Install Directory
On Linux systems running systemd, you can choose a dedicated directory for the agent binary, configuration, and application data instead of the standard locations. Choose the directory when installing. This option does not move an existing installation to a new path.
Directory requirements
Use an absolute path reserved for Level, such as
/srv/level. For a new installation, use an empty directory. You can also reuse a directory containing an existing Level installation at that same path.The filesystem must allow writing and execution. A read-only or
noexecfilesystem cannot be used.The directory must be owned by root, must not allow group or other write access, and must allow other users to traverse it. Its parent directories must also be root-controlled and traversable by other users. Mode
755is suitable for a dedicated root-owned Level directory.Spaces are allowed if you quote the path in your command. Do not use control characters, single or double quotes, percent signs, dollar signs, backslashes, or backticks in the path. Do not use a shared system directory such as
/,/mnt,/opt,/tmp, or/var/libas the installation root.
One-line command with a custom directory
Copy your Linux one-line command from Add new device, including the install key and any device-group selection.
Add
LEVEL_INSTALL_DIR="/srv/level"beforeLEVEL_API_KEY=..., replacing the example path with your chosen directory. The parent directory must already exist. The script creates the final Level directory if it is missing.Run the modified command. For example, with your install key substituted for
YOUR_INSTALL_KEY:
LEVEL_INSTALL_DIR="/srv/level" LEVEL_API_KEY="YOUR_INSTALL_KEY" bash -c "$(curl -L https://downloads.level.io/install_linux.sh)"
The script stages its download in a private temporary directory inside the selected installation directory and passes that directory to the agent installer. Use the environment variable for the shell script; use --install-dir when running the downloaded agent binary directly.
Downloaded installer with a custom directory
Create the dedicated directory first and ensure it meets the requirements above. Append --install-dir "/srv/level" to the generated install command. For an x64 installer, the command is:
chmod +x ./level-linux-amd64 && sudo ./level-linux-amd64 -k YOUR_INSTALL_KEY -a install --install-dir "/srv/level"
Replace YOUR_INSTALL_KEY and the path before running the command, and use the binary for your device's architecture. The downloaded binary must be on an executable filesystem. If an existing Level service points to another installation directory, the installer rejects the change, including with force install. Contact Level support before changing an existing installation's location.
TrueNAS Storage and Reboot Persistence
For Linux-based TrueNAS deployments, use the storage and startup requirements below. Contact Level support to confirm compatibility for your exact TrueNAS edition and release before installing.
Choose a dedicated Level directory or dataset on a ZFS storage pool under
/mnt/, for example/mnt/tank/level. Replacetankwith your pool name. Do not select the boot pool or the storage pool root itself.Import the pool, unlock any encrypted dataset, and mount the installation dataset before installing. The dataset must be writable and permit execution, and the path must meet the custom-directory ownership and permission requirements above.
Use the custom-directory one-line command above with your TrueNAS path in
LEVEL_INSTALL_DIR. The installer checks the mounted ZFS dataset before proceeding.After installation, check TrueNAS Init/Shutdown Scripts for the automatically registered Level Agent boot service task. It is an enabled Command task set to Post Init. Keep that task enabled and preserve the installation directory and its startup files. You do not need to create a second startup task manually.
The installer saves Level.service, 10-truenas.conf, and start-level.sh in the installation directory. At boot, the Post Init command waits until the saved startup script is readable, checking every 60 seconds. The script restores the runtime unit at /run/systemd/system/Level.service and its mount-requirement drop-in at /run/systemd/system/Level.service.d/10-truenas.conf, then starts the service.
The installation dataset must be available for the agent to run. If it remains encrypted and locked after boot, unlock and mount it through your normal TrueNAS storage workflow. The startup task does not unlock the dataset for you.
Force Install (Advanced)
If a previous Level install left behind stale files, use the forceInstall URL parameter to force a clean overwrite.
Navigate to:
https://app.level.io/devices?forceInstall=true
This adds LEVEL_FORCE_INSTALL=true to the generated one-line command.
⚠️ WARNING: Force install overwrites any existing Level agent configuration on the device. Only use this when a standard install fails or Level support directs you to.
System Requirements
Supported Distributions
Distribution | Minimum Version |
AlmaLinux | Current stable |
Arch Linux | Current stable |
CentOS | 8 |
Debian | 10 |
Fedora | 36 |
Fedora Silverblue / COSMIC Atomic (rpm-ostree) | Current stable |
Linux Mint | 20 |
Photon OS (VMware) | Current stable |
Raspbian (Raspberry Pi OS) | Current stable |
Red Hat Enterprise Linux (RHEL) | 8 |
Rocky Linux | 8 |
Sangoma Linux | Current stable |
Ubuntu | 20.04 LTS |
🖥️ PLATFORM NOTE: rpm-ostree systems such as Fedora Silverblue and COSMIC Atomic are supported. The agent writes its systemd restart delay through a drop-in and stores desktop entries under /usr/local/share, so it does not write to read-only system paths. Pending rpm-ostree deployments are detected for reboot checks.
ℹ️ NOTE: Other distributions may work but aren't officially supported. If you run into issues on an unlisted distro, contact Level support.
Required Dependencies
The following packages must be present on the target system before installing:
sudosystemd(for service management)dbusor a UUID in/etc/machine-idcurlca-certificatesbash
Most supported distributions include these by default. On minimal installs, verify before running the Level install command.
Storage Locations
The paths below are the standard binary and data locations. The standard configuration file is /etc/level/config.yaml.
Path | Purpose |
| Agent binary |
| Agent data |
Custom-directory storage
With /srv/level selected as the custom installation directory, Level uses:
/srv/level/bin/levelfor the agent binary./srv/level/config.yamlfor configuration./srv/levelfor application data, including logs and the local database.
The systemd service retains the selected directory in its --install-dir argument. For TrueNAS, substitute your /mnt/... installation path; the saved startup files described above also stay in that directory.
After Install
The device appears in your Device Listing within 5–10 seconds and starts populating hardware inventory within a few minutes.
If the device doesn't appear, see Offline Troubleshooting for next steps.
FAQ
Is the install key the same as an API key? No. The install key (from Add new device) only enrolls devices into your account. API keys (from Settings → API keys) authenticate external tools against Level's API. You can't install the agent with an API key. Use the install key from the install modal. See API Keys Settings.
Do I need to run the install command as root? Yes, the agent needs elevated permissions to install. The one-line command includes
sudoautomatically. For the manual installer, run the command withsudoor as root directly.Which architecture should I select in the Installer tab? Select x64 for standard 64-bit Intel/AMD systems and ARM for ARM-based devices (including Raspberry Pi). The one-line command method handles architecture detection automatically.
Can I install Level on Fedora Silverblue or COSMIC Atomic? Yes. Those rpm-ostree systems are in the supported table. Use the native installer. The agent does not write to read-only system paths. Other immutable distributions may work if they meet the dependency requirements, but they are not officially tested.
My Linux distro isn't on the supported list, will Level still work? Possibly. Level supports most modern distributions running systemd. If your distro meets the dependency requirements, it may work fine. Contact Level support if you run into issues.
The device installed but isn't showing up in Level, what's wrong? Wait 10–15 seconds and refresh. If it still doesn't appear, verify systemd is running and all required dependencies (
curl,dbus, etc.) were present during install. See Offline Troubleshooting for further steps.What if my install key is compromised? The install key can't access your account, existing devices, or the Level API. The only risk is someone adding devices to your account. Contact Level support to rotate the key if needed.
Can I deploy the agent to many Linux devices at once? Yes. Use the one-line command with your existing tooling (Ansible, Puppet, Chef, bash over SSH, etc.).
Who can add devices to Level? Any technician with permission to manage the target device group, or any technician if deploying to Ungrouped. Check Workspace → Permissions if you don't see the Add new device button.



