Skip to main content
Getting Started

Step 3 – Deploy Your First Agent

Install the octoja agent on a device so it can be monitored

The octoja agent is a small program that runs on a computer or server. Once installed, it connects directly to the octoja web service and sends health data — CPU usage, memory, disk space, running services, and more — so you can monitor the device remotely.

Before you start

  • Your octoja user needs the Agent Management permission — without it, Agent Deployment does not open. Administrators have it already.
  • You need administrator rights on the device you are installing the agent on.
  • The device needs an internet connection (outbound HTTPS on port 443).
  • You should have already created the customer this device belongs to (see Step 2).

Steps

  1. In octoja, go to Administration → Agent Deployment in the left sidebar.

  2. Step 1 – Settings. Choose Open Deployment only if your octoja instance allows enrollment without a token. This selection generates an install command without a token; it does not change the enrollment policy. If your instance requires a token, choose Token-based Deployment and a valid enrollment token. Your administrator can provide one using the enrollment-token guide.

  3. Step 2 – Choose Platform. Select the operating system of the device: Windows, Linux, or macOS.

  4. Step 3 – Choose Installation Method. For your first agent, Quick Install is recommended. It runs a single command that auto-detects the architecture and installs the agent silently.

  5. Step 4 – Install. Copy the install command shown in the grey code block and run it on the target device:

PlatformHow to run
WindowsOpen PowerShell as Administrator, paste the command, press Enter
LinuxOpen a terminal, paste the command, press Enter. It runs with sudo — enter your password when prompted
macOSOpen Terminal, paste the command, press Enter. It runs with sudo — enter your password when prompted

Step 4 Install of the deployment wizard with the PowerShell install command in a grey code block. The copy button at the top-right of the code block is outlined in red; the command text extends beyond the visible crop (readers copy it from the live interface, not from this image).

Copy the command from the octoja interface. Do not type it from this article — it contains your unique server URL.

On Windows, Quick Install automatically installs missing prerequisites, including Microsoft Visual C++ Redistributable and .NET Framework. If .NET Framework setup requires a restart, the script stops before installing the agent. Restart Windows yourself, then run the command again. See the Windows deployment guide for download requirements and possible effects on running services.

  1. Step 5 – Verification. When the install command finishes, go to Devices in the sidebar. The device appears within seconds. In the narrow status column headed S., the device icon gets a green ring as soon as the agent is online. The Health column shows a dash — that column summarises check results, and this device has no checks yet. It turns into a green tick once you activate your first check in Step 4.

octoja Devices table immediately after enrollment. The newly-enrolled device CONTOSO-DC01 appears at the top of the list with its server-shape status icon in the "S." column outlined in blue. The Health column shows an em-dash while initial telemetry is still in flight; it turns green within 1-2 minutes once the agent reports.

Once you are ready to lock enrollment down

For production, your administrator opens Settings → Agent enrollment policy and turns Allow open deployment off. This setting requires a valid enrollment token for new enrollments. Selecting Token-based Deployment in the deployment wizard only adds a token to the install command; it does not block enrollment without a token. Only administrators can change the policy; Agent Management alone is insufficient. See Configure Agent Enrollment Tokens.

Troubleshooting

ProblemWhat to do
Device does not appear after 5 minutesCheck the device has internet access. Try loading any website in a browser. If that works, restart the agent service on the device.
Installation fails on WindowsRun PowerShell as administrator. Windows requires admin rights to install services.
Installation fails on Linux or macOSThe command needs root rights. Run it from an account that can use sudo, and enter the password when the terminal asks.
Agent shows as disconnectedRestart the device and wait 2 minutes. If still disconnected, check no firewall blocks outbound HTTPS (port 443).

Need more detail? See the full deployment guides:

Next step

Continue to Step 4 – Activate Your First Check.

Was this helpful?

Still need help? Ask the team