Step 3 – Deploy Your First Agent

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

Written By Erdinc Akay

Last updated 28 days ago

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.

The Agent Deployment page in octoja with the multi-step wizard. The page title "Agent Deployment" is outlined in red. The "Allow open deployment" toggle is enabled in the top-right. Step 1 Settings shows the Open Deployment and Token-based Deployment option tiles with Open Deployment selected; Step 2 Choose Platform shows Windows, Linux, and macOS; Step 3 Choose Installation Method shows Quick Install, Manual Install, and Automatic Rollout.

Before you start

  • 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. For your first agent, keep the default Open Deployment option. This lets any device with the correct server URL enroll immediately, so you can get a device connected without any additional setup.

  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
macOSOpen Terminal, paste the command, press Enter
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.

  1. Step 5 – Verification. Wait 1–2 minutes, then go to Devices in the sidebar. The device should appear in the list and the status dot lights up green. The Health column may show a dash for the first minute or two before it turns green — the agent is connected, the first telemetry is simply still on its way.
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

Open deployment is fine while you are learning the product. For production, your administrator should switch to Token-based Deployment so only devices with a valid enrollment token can connect. See Configure Agent Enrollment Tokens for the admin setup.

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.
macOS blocks the installerGo to System Settings → Privacy & Security and click Open Anyway. This is Gatekeeper — macOS blocks unidentified developers by default.
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.