Unmeshed Logo

CLI & Remote Agents

Darwin (macOS) Agent Installation Guide

This guide covers the current native macOS agent workflow driven by the Unmeshed CLI.

The normal installation path is:

bash

Prerequisites

Install the CLI on the macOS host first:

Run the installer

Start the install:

bash

The current installer prompts for:

  • the install directory
  • the service name
  • whether to install the latest version or select a recent version

Default values on macOS:

  • install directory: ~/unmeshed-agent
  • service name: unmeshedagent

What the installer creates

After the download completes, the macOS installer creates or records:

  • the native agent binary, for example unmeshed-agent-darwin-arm64
  • the native monitor binary, for example unmeshed-monitor-darwin-arm64
  • unmeshed.properties
  • processes.yaml
  • a generated launcher name derived from the service name, such as unmeshedagent-abc
  • an agent entry in ~/.unmeshed/config.yaml
  • a LaunchAgent plist at ~/Library/LaunchAgents/com.unmeshed.<service-name>.plist

The LaunchAgent is written with:

  • Label=com.unmeshed.<service-name>
  • ProgramArguments=<install-dir>/<monitor-binary>
  • WorkingDirectory=<install-dir>
  • RunAtLoad=true
  • KeepAlive=true
  • StandardOutPath=<install-dir>/<service-name>.log
  • StandardErrorPath=<install-dir>/<service-name>.log

The CLI also sets UNMESHED_HOST_NAME in the LaunchAgent environment when it can determine the host name.

Configure the agent

Before starting the LaunchAgent, edit:

text

The current installer seeds these keys:

properties

UNMESHED_CUSTOM_TLS_CERTS_DIR points at the generated customcerts directory under the install path. If the agent must trust a self-signed or otherwise untrusted certificate chain, use Load certificates for self-signed or untrusted HTTPS endpoints.

Worker names use:

text

Example:

properties

Load and manage the LaunchAgent

Immediately after install, the CLI prints the path to the generated plist and tells you it can be loaded with:

bash

For repeatable start and restart operations, the CLI's agent-info summary prints commands like these:

bash

If you want the CLI to reprint the current service instructions for an installed agent, run:

bash

Verification

Confirm that the worker names you configured in unmeshed.properties appear as connected workers in the platform.

For list-agents, agent-info, update-agent, uninstall-agent, and offline agent update guidance, see Remote Agent Lifecycle.

Offline installation

If the target macOS machine cannot reach the CLI or agent download hosts directly, use Download the CLI for another machine to stage the CLI binary and Install from local binaries to install the agent from copied binaries.

After install-agent --use-local-binaries completes, continue with the normal configuration and LaunchAgent steps in this guide.

Related Documentation