Deploy the Agent on macOS

This guide walks you through installing and registering the octoja Agent on a macOS system.

Prerequisites

• macOS 12 (Monterey) or newer. Remote Desktop sessions to the Mac need macOS 14 or newer.
• The Agent Management permission in octoja — without it, the Agent Deployment page is not available. Permissions come from your group memberships under Administration → Groups.
• Admin account on the Mac
• Internet access (outbound HTTPS on port 443)

About enrollment settings

The Agent Deployment page opens with Step 1 – Settings, where you decide how new agents authenticate. Two cards are offered: Open Deployment ("Any device with the server URL can enroll.") and Token-based Deployment. octoja never creates tokens on its own — choosing Token-based Deployment opens the Configure Deployment dialog, where you optionally assign a customer, site, and expiration date and then explicitly create the installation token. The install command shown later in Step 4 – Install embeds that token automatically, so you only need to copy the command verbatim.

The "…" menu in the page header holds Manage tokens, which opens the Enrollment tokens page where you can create and delete tokens. That page lists the tokens for the customers you can reach; tokens that cover all customers stay with accounts that can reach every customer. Administrators set the instance-wide policy under Settings → Agent enrollment policy; turn off Allow open deployment there to require an enrollment token for every new agent.

Steps

1. In octoja, go to Administration → Agent Deployment. The page is laid out as five numbered cards: Settings, Choose Platform, Choose Installation Method, Install, and Verification.
2. In Step 1 – Settings, choose Open Deployment (no token required) or Token-based Deployment — and create the installation token when the dialog prompts you.
3. In Step 2 – Choose Platform, click macOS.
4. In Step 3 – Choose Installation Method, choose Quick Install or Manual Install.
5. In Step 4 – Install, copy the command or download the ZIP archive shown in the card.
6. Step 5 – Verification shows the in-product confirmation hint once the agent reports in.

Quick Install

Copy the command verbatim from the Install card and paste it into Terminal on the Mac. The install.sh script is hosted on the octoja CDN, not on your octoja instance — copy the full command rather than retyping the URL:

curl -fsSL '<install.sh URL from the Install card>' | sudo bash -s -- 'https://YOUR-OCTOJA-URL'

With Token-based Deployment, octoja appends the token as a second positional argument — again, copy the command verbatim:

curl -fsSL '<install.sh URL from the Install card>' | sudo bash -s -- 'https://YOUR-OCTOJA-URL' 'YOUR-TOKEN'

You will be prompted for the Mac admin password.

Manual Install (.pkg)

1. In Step 4 – Install, download the octoja_osx-<arch>.zip archive from the Manual Install panel (pick the ARM64 or X64 tab to match your Mac) and extract it. The archive contains the package (octoja_<version>_<arch>.pkg) and the installer script install.sh side by side.
2. Open Terminal (Applications → Utilities → Terminal), change into the extracted folder, and run install.sh — the script is the installer for the manual path:

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

With Token-based Deployment, pass the token as the second argument:

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

The script first checks that your octoja server is reachable, then writes the connection settings to /opt/octoja/etc/installer.settings.json, and finally installs the .pkg through the native macOS installer. The agent services start automatically — no installer window appears.

Do not install by double-clicking the .pkg file. On its own, the package does not know your octoja server URL — the installation fails and the agent services are not started. Always install through install.sh, or through the sidecar file described below.

The Agent Deployment page's Step 5 – Verification card confirms the rest: "You're all set! The agent will show up on the Devices page within seconds — ready to manage." Open Devices to see your new Mac.

Alternative: sidecar JSON file

For unattended installs — for example through MDM — you can create the connection settings yourself instead of running install.sh: drop the server URL (and token, if required) into /opt/octoja/etc/installer.settings.json, then run the package through the native macOS installer (installer -pkg):

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

With Open Deployment, omit the "token" entry.

Then install the package:

sudo installer -pkg octoja_<version>_<arch>.pkg -target /

Prepare remote support

After a fresh installation, the agent offers the signed-in user a one-time setup for missing macOS remote-support permissions. In the Remote support permissions window, click Set up for each missing permission and allow octoja Agent under System Settings → Privacy & Security: Screen & System Audio Recording for video and Accessibility for mouse and keyboard control.

If you closed the window or want to continue later, choose Remote support permissions from the octoja menu-bar icon. The icon only appears when Show agent in system tray is on for the device. Without it, the window opens again when a remote desktop session starts while permissions are still missing. Closing the window does not grant permissions. Reinstalling on an already configured device does not show the one-time offer again.

See Use Remote Desktop for prerequisites and connecting.

Verify the agent is running

The octoja Agent runs as a launchd service — the macOS equivalent of a Windows service. Open Terminal (Applications → Utilities → Terminal) and run the following command:

sudo launchctl list | grep octoja

If the com.octoja.agent line shows a process ID in the first column, the agent is running; a - means it is not running right now. The com.octoja.service-recovery line usually shows -: this recovery job only runs briefly every five minutes and starts stopped agent services again.

Manage the agent service

Mass deployment (MDM)

On macOS, deploy the agent at scale via your existing MDM tooling. (The built-in Automatic Rollout tab in octoja covers Intune and Group Policy and applies to Windows.)

If you manage Macs with an MDM (Mobile Device Management) tool such as Jamf, Mosyle, or Kandji, you can deploy the .pkg file silently to all managed Macs — without manual interaction. Use the sidecar JSON file method above to supply the server URL and token.

MDM (Mobile Device Management) lets IT administrators deploy software to managed devices remotely; consult your MDM vendor's documentation or Apple's MDM overview for the steps specific to your tool.

Need an enrollment token? See Configure Agent Enrollment Tokens.

FAQ