Deploy Agent on Linux

Step-by-step guide to installing and deploying the octoja agent on Linux.

Prerequisites

An octoja account with the Agent Management permission — without it, Administration → Agent Deployment does not appear in your navigation
Ubuntu 22.04 LTS or 24.04 LTS, Debian 12 or 13, or a RHEL-family system from version 8 (x64 or arm64)
Root or sudo access
Internet access (outbound HTTPS on port 443)

Cloned devices and master images

Install the octoja agent separately on each device after cloning, rather than including an already-enrolled agent in the master image. Cloning an enrolled agent copies its device identity, so multiple machines can appear as one device and remote actions can reach the wrong clone.

If this has already happened, avoid remote actions on the affected entry and contact support. Renaming the device or rerunning the installer does not reset its octoja identity.

Key terms

This guide uses some Linux commands. Here is what they mean:

Term	Explanation
Terminal	A text-based interface for entering commands. On a Linux desktop, search for "Terminal" in the application menu. On a server, you are typically already in a terminal.
sudo	A command prefix that runs the following command with administrator (root) privileges. You may be prompted for your password.
curl	A command-line tool for downloading files from the internet.
systemctl	A command for managing background services (part of systemd, the service manager used by all modern Linux distributions).

Steps

In octoja, navigate to Administration → Agent Deployment.
In Step 1 – Settings, choose the enrollment mode for the install command. Open Deployment generates a command without a token and only works if your octoja instance's enrollment policy allows it. Token-based Deployment adds the selected enrollment token to the command. This selection does not change the policy.
In Step 2 – Choose Platform, click Linux.
In Step 3 – Choose Installation Method, select Quick Install for a single device or Manual Install if you need a custom package.
In Step 4 – Install, copy the command from the panel and run it on the Linux device (see below).
In Step 5 – Verification, confirm the new device shows up. You can also navigate to Devices. The device usually appears within seconds of the install finishing.

To require a token for new enrollments, an administrator opens Settings → Agent enrollment policy and turns Allow open deployment off. Agent Management alone does not allow this change. See Configure enrollment tokens.

Quick install (recommended)

Copy the quick install command from the deployment page. It looks something like this:

curl -fsSL 'https://cdn.octoja.com/installer/install.sh' | sudo bash -s -- 'https://YOUR-OCTOJA-URL'

If you selected Token-based Deployment in the wizard, the command includes the token as a second positional argument:

curl -fsSL 'https://cdn.octoja.com/installer/install.sh' | sudo bash -s -- 'https://YOUR-OCTOJA-URL' 'YOUR-TOKEN'

Copy the command directly from octoja. It already contains the server URL (and the token if applicable). The example above will not work without modification.

The script detects the architecture, downloads the matching package, installs it, and starts the octoja-launcher and octoja-agent services. If the ICU runtime or jq is missing, the script installs them first and says so — the agent needs ICU to start, and the Linux monitoring and automation scripts need jq.

Before it finishes, the script confirms that both services are really running. If one of them did not come up, the script stops with an error and prints the last 20 log lines for that service, so you can see what went wrong. The full logs live under /opt/octoja/logs/agent/ and /opt/octoja/logs/launcher/.

Manual install

On the deployment page, select Manual Install to download the agent ZIP archive directly. Extract it, then from inside the extracted directory, run the bundled install.sh with your server URL:

sudo bash install.sh https://YOUR-OCTOJA-URL

If a token is required, pass it as the second argument:

sudo bash install.sh https://YOUR-OCTOJA-URL YOUR-TOKEN

The archive contains .deb and .rpm packages. The script selects .deb with dpkg on Debian-family systems or .rpm with dnf/rpm on RHEL-family systems. It places the agent under /opt/octoja and starts the octoja-launcher and octoja-agent services. Keep the package files beside install.sh when running it.

How the sidecar settings file works

When you run install.sh with a server URL (and optional token), it writes those values to a settings file at /etc/octoja/installer.settings.json. The package's post-install step then reads that file to configure the agent — it does not read the command-line arguments directly.

If the sidecar file is missing when the package is installed, the post-install step prints a note asking you to edit launcherconfig.xml manually. You can also pre-create the sidecar file yourself before installing the package, for example when staging an image:

sudo mkdir -p /etc/octoja
sudo tee /etc/octoja/installer.settings.json <<'EOF'
{
  "octojaUrl": "https://YOUR-OCTOJA-URL",
  "token": "YOUR-TOKEN"
}
EOF

Check agent status

The octoja agent runs as two systemd services — background programs that start automatically at system boot:

octoja-launcher — manages updates and supervises the agent process.
octoja-agent — the actual agent that connects to your octoja server.

Check the status of both with the following commands:

systemctl status octoja-launcher
systemctl status octoja-agent

Both should show active (running). If either shows inactive or failed, restart it:

sudo systemctl restart octoja-launcher
sudo systemctl restart octoja-agent

Manage the agent services

The launcher also sets up the octoja-service-recovery.timer timer. Every five minutes it checks whether both services are running and starts a stopped service again. Running systemctl stop on the two services alone therefore only stops them until the next check.

Command	Description
systemctl status octoja-launcher	Check if the launcher is running
systemctl status octoja-agent	Check if the agent itself is running
sudo systemctl restart octoja-launcher octoja-agent	Stop and restart both services
sudo systemctl stop octoja-service-recovery.timer octoja-launcher octoja-agent	Stop both services and the recovery timer (they will start again on next reboot)
sudo systemctl start octoja-launcher octoja-agent	Start both services if they are stopped; the launcher also re-enables the recovery timer
journalctl -u octoja-agent -f	Follow the agent log output in real time (Ctrl+C to exit)

Need an enrollment token? See Configure Agent Enrollment Tokens.

FAQ

How do I install the agent as root when sudo is missing?

Run id -u to check whether your shell is already running as root: the output must be 0. Then remove only sudo before bash from the copied installation command; keep the server URL and any enrollment token unchanged. This also applies to a root shell on a Proxmox host. As a regular user, you still need root privileges.

Why does RPM report “nothing provides jq” when jq is installed?

RPM needs a package that provides the dependency, not just an executable on disk. Compare command -v jq with rpm -q --whatprovides jq. If only the first succeeds, send both outputs and the installation error to support. On vendor-managed appliances, confirm supported package sources with the vendor; do not bypass dependency checks or add unapproved repositories.

Was this helpful?

Still need help? Ask the team