Unmeshed Logo

CLI & Remote Agents

Remote Agent Lifecycle

Use this page for the agent-management commands that live directly in the CLI, including agent installation, inspection, updates, offline binary downloads, and certificate loading for agents that must trust additional HTTPS certificate chains.

The native CLI-managed agent flow currently applies to Linux, macOS, and Windows. For IBM i, see the separate IBMi/AS400 Installation guide.

What the installer records locally

The CLI keeps installed-agent metadata in:

text

Each recorded agent entry includes:

  • the install path
  • the service name recorded during installation

Inside the install directory, install-agent also creates:

  • the platform agent binary, such as unmeshed-agent-linux-amd64
  • the platform monitor binary, such as unmeshed-monitor-linux-amd64
  • unmeshed.properties
  • processes.yaml
  • customcerts/
  • a generated launcher name derived from the service name, such as unmeshedagent-abc

Install an agent

Start with:

bash

The current flow prompts for:

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

Default install directories:

  • Linux: /unmeshed/agent
  • macOS: ~/unmeshed-agent
  • Windows: ~/unmeshed-agent

Default service name:

text

Platform-specific behavior:

  • Linux: the CLI writes a systemd unit and reloads systemd
  • macOS: the CLI writes a LaunchAgent plist under ~/Library/LaunchAgents
  • Windows: the CLI downloads the binaries and prints manual run and sc service commands instead of registering the service automatically

Install from local binaries

If the binaries are already on disk, use:

bash

If --local-binaries-dir is omitted, the current working directory is used.

Download agent binaries for offline installs

Use:

bash

The command prompts for:

  • target OS and architecture
  • version
  • download directory

The current target list includes:

  • darwin/amd64
  • darwin/arm64
  • linux/amd64
  • linux/arm64
  • windows/amd64
  • windows/arm64

After the download finishes, the CLI prints the exact install-agent --use-local-binaries command to run later on the target machine.

Load certificates for self-signed or untrusted HTTPS endpoints

If an installed agent must trust a certificate chain that is not already trusted on that machine, use:

bash

Current behavior:

  • finds the installed agent by its recorded service name
  • connects to the HTTPS endpoint you provide
  • captures the presented TLS certificate chain
  • writes the PEM bundle into <install-dir>/customcerts

The generated unmeshed.properties file already sets UNMESHED_CUSTOM_TLS_CERTS_DIR to that customcerts directory.

After loading a certificate bundle, restart the agent service so the running agent picks up the updated trust material.

List installed agents

Use:

bash

The command reads ~/.unmeshed/config.yaml, prints the recorded agent paths and service names, and automatically removes entries whose install paths no longer exist.

Inspect an installed agent

Use:

bash

If more than one agent is recorded, the CLI prompts you to choose one. It then prints:

  • the agent directory
  • the service name
  • current service status
  • the same post-install configuration and service commands shown after installation

This is the quickest way to re-display the service commands for an installed agent without reinstalling it.

Update an installed agent

Use:

bash

Current behavior:

  • finds the installed agent binary in the recorded install directory
  • reads its current version
  • compares it with newer versions in the download store
  • prompts you to choose a newer version
  • stops the recorded service when a service name is available
  • replaces the agent and monitor binaries
  • starts the service again when a service name is available

If the CLI on the destination machine does not have internet access, update-agent cannot download a newer version for you. Use this workflow instead:

  1. On a machine with internet access, run unmeshed download-agent and download the target version for the destination platform.
  2. Stop the agent service on the destination machine before replacing binaries.
  3. Copy the downloaded agent and monitor binaries into the recorded install directory on the destination machine.
  4. Replace the existing binaries in that install directory.
  5. Start the agent service again.

Uninstall an installed agent

Use:

bash

Current behavior:

  • prompts you to choose which recorded agent to remove
  • shows the recorded service and install paths before confirmation
  • removes the service when the current platform supports automated removal
  • cleans the install directory while preserving *.log files
  • removes the agent entry from ~/.unmeshed/config.yaml

Platform-specific install guides

Related Documentation