Skip to content

Install the host agent in an office

One agent per server, built on the OpenTelemetry Collector, sends host metrics every 60 seconds and the server's facts every 10 minutes over outbound HTTPS. It opens no port to your network.

How do I install it?

  1. Add the site

    On the connect page, choose On-prem and add a site. Its install token is shown once and enrols every server there.

  2. Run the installer on each server

    The connect page fills in the address and version. The installer asks for the site token, so it never lands in your shell history.

    Linux
    curl -fsSL <your MarshalCloud API address>/agent/host/install.sh -o marshal-agent-install.sh
sudo MARSHAL_ENDPOINT=<your MarshalCloud API address> MARSHAL_AGENT_VERSION=<version> \
  sh marshal-agent-install.sh
    Windows (elevated PowerShell)
    Windows (elevated PowerShell)
    $env:MARSHAL_ENDPOINT = "<your MarshalCloud API address>"
$env:MARSHAL_AGENT_VERSION = "<version>"
Invoke-WebRequest -UseBasicParsing "<your MarshalCloud API address>/agent/host/install.ps1" -OutFile marshal-agent-install.ps1
powershell -ExecutionPolicy Bypass -File .\marshal-agent-install.ps1

How you know it worked. Each server appears under its site on the connect page about a minute after the install. Servers have no bill: enter the site's cost on On-prem costs.

Signed in? Open this guide with your own valuesNot signed in: sign in, then open Settings, Setup guides.

What do I need first?

  • Your own servers (sites) are early access on Growth and Scaled, with a server allowance we set for your workspace when you ask.
  • Linux: systemd, curl, root (sudo), and an amd64 or arm64 CPU.
  • Windows Server: 64-bit and an elevated PowerShell. Windows reports host name, operating system, CPU and IP addresses only for now.
  • Docker: not ready. No agent image is published, and in a container it would report the container rather than the server.
  • Outbound HTTPS (443, TLS 1.2 or later) to MarshalCloud's API address only. Behind a proxy, give the installer HTTPS_PROXY; a proxy that inspects TLS also needs MARSHAL_CA_FILE.

What access does it grant?

What it installs

  • Linux: the binary at /usr/bin/marshal-agent, its config in /etc/marshal-agent, a root-only env file there holding the endpoint and site token, and a systemd unit, marshal-agent.service.
  • Linux: a dedicated marshal-agent user and group, and /var/lib/marshal-agent for its own token (readable by that user only) and its send queue.
  • Windows Server: a service named marshal-agent running as LocalSystem, with files in Program Files and ProgramData under Marshal\marshal-agent, readable only by SYSTEM and Administrators. The Windows installer has not yet been run on a real Windows host; treat it as early.
  • Every download is checked against a checksum file signed with MarshalCloud's release key before anything is installed.

What it can do

  • Send CPU, memory, disk, filesystem, network and load figures every 60 seconds.
  • Send the server's facts every 10 minutes: host name, operating system, kernel, CPU cores, memory, IP addresses, filesystems, services, listening ports and the number of installed packages.
  • Run the private checks you assign to its site (web, TCP and DNS checks on addresses only your network can reach), if it is the site's chosen prober.
  • Accept telemetry from apps on the same server at 127.0.0.1:4318, and forward it.

What it never does

  • Accept connections from other machines: its only listener is on 127.0.0.1.
  • Change anything on the server, or read file contents.
  • Write a token into its logs: an error is logged as its HTTP code only.
  • Run as root on Linux: it runs as its own marshal-agent user under a hardened systemd unit.

How do I check or remove it?

  1. Check it is running

    Is the agent running, and what did it last log?

    Linux
    systemctl status marshal-agent --no-pager
journalctl -u marshal-agent -n 50 --no-pager
    Windows
    Windows
    Get-Service marshal-agent

  2. Uninstall the agent from each server

    On Linux the installer removes exactly what it wrote: the service, the binary, the config, the token, the queue, and the marshal-agent user and group.

    Linux
    sudo sh marshal-agent-install.sh --uninstall
    Windows (elevated PowerShell)
    Windows (elevated PowerShell)
    Stop-Service marshal-agent -ErrorAction SilentlyContinue
sc.exe delete marshal-agent
Remove-Item -Recurse -Force "$env:ProgramFiles\Marshal\marshal-agent"
Remove-Item -Recurse -Force "$env:ProgramData\Marshal\marshal-agent"

  3. Revoke the server

    In MarshalCloud, press Revoke on each removed server under its site on the connect page, so its token stops working. To stop new installs at the site, press Stop new installs, or disconnect the whole site in Settings, Accounts (owners only).