hostatlas-agent is a single static Go binary that runs as a systemd service on each server you want to monitor. It collects system metrics, discovers running services, parses web server configs, enumerates domains, SSL certificates, Docker containers, and open ports, and pushes them all to the HostAtlas platform for analysis.

The agent collects data only — every alert, correlation, and recommendation happens platform-side. That’s what keeps the on-host footprint small and predictable.

Tip

Looking for step-by-step install instructions? See Getting Started → Install the Agent. This page is the tool reference.

Install

One-liner with your install key from Settings → Install Keys:

curl -sSL https://install.hostatlas.app | bash -s -- --key=YOUR_INSTALL_KEY

The installer:

1. Detects your OS + architecture (amd64 or arm64)
2. Downloads the matching binary from install.hostatlas.app/agent/latest/
3. Verifies the SHA-256 checksum
4. Registers the host with the platform using your install key
5. Writes /etc/hostatlas/agent.yml with the agent’s own credentials
6. Installs and enables the systemd unit

Bulk install from ~/.ssh/config + /etc/hosts

If you have many hosts, use the CLI’s hostatlas onboard command from your laptop — it reads your local SSH config and /etc/hosts, presents a checkbox picker, and mints one fresh install key per host.

Manual install (build from source)

git clone https://github.com/akyroslabs/hostatlas-agent.git
cd hostatlas-agent
go build -o hostatlas-agent ./cmd/agent/

# Register
./hostatlas-agent --key=YOUR_INSTALL_KEY --api=https://api.hostatlas.app

# Run
./hostatlas-agent

Direct downloads

Binaries live at https://install.hostatlas.app/agent/latest/:

Platform	File
Linux (x86_64)	hostatlas-agent-linux-amd64
Linux (ARM64)	hostatlas-agent-linux-arm64

The top-level https://install.hostatlas.app/agent/version.json carries the full list under binaries[] (filename, size, sha256, url) and both folders publish a files.json sidecar for checksum verification.

Configuration

Config file at /etc/hostatlas/agent.yml (mode 0600, root-owned):

agent_id: "your-agent-uuid"
agent_token: "your-agent-token"
api_url: "https://api.hostatlas.app"
metrics_interval: 30          # seconds
discovery_interval: 300       # seconds
command_poll_interval: 5      # seconds
remote_commands_enabled: true

Key	Purpose	Default
agent_id	UUID of the server (written by the installer)	—
agent_token	Long-lived agent token (written by the installer)	—
api_url	HostAtlas API endpoint	https://api.hostatlas.app
metrics_interval	System-metric push interval, seconds	30
discovery_interval	Service-discovery interval, seconds	300
command_poll_interval	How often the agent asks the platform for pending commands	5
remote_commands_enabled	Whether the agent will execute whitelisted commands sent from the platform	true

What it collects

System metrics (every metrics_interval seconds):

• CPU usage (per-core + aggregate)
• RAM usage (used / cached / buffers / free)
• Disk usage per mount
• Network I/O per interface
• Uptime and load averages (1m / 5m / 15m)
• Public IP (via ip.hostatlas.app, CGNAT/Tailscale ranges filtered out)
• Hostname (synced on every heartbeat)

Service discovery (every discovery_interval seconds):

• Running services: nginx, apache, mysql, mariadb, postgresql, redis, caddy, docker
• Web server vhosts / server-blocks with domain + document root + SSL status
• Docker containers (name, image, ports, status)
• SSL certificates (Let’s Encrypt + others) with expiry
• Open ports and listening processes

Sensitive-config filtering — SSL private keys, auth headers, secrets and credentials are excluded before the agent transmits any nginx / apache config.

Cron sanitization — cron entries containing passwords, tokens, or secrets are masked before upload.

Remote commands

When remote_commands_enabled: true, the agent polls for pending commands from the platform every command_poll_interval seconds. Only whitelisted actions are executable:

• restart_service <name> — restart a systemd unit
• run_recipe <recipe-uuid> — execute a HostAtlas recipe (delegated to the Server CLI when present)
• provision_domain <domain> — create vhost + document root + SSL cert + logrotate
• network_diagnose <target> — ping / traceroute (private-IP + DNS-resolution checks block IPv4/IPv6 private ranges)
• self_update — download the latest agent binary from install.hostatlas.app/agent/latest/, verify checksum, replace, restart under systemd
• collect_logs <path> — return a log tail for the platform (with size caps)

Every command execution lands in the HostAtlas audit trail with parameters, output, exit code, and timestamp.

Self-update

Two paths:

• CLI flag — hostatlas-agent -update downloads the latest release, verifies the checksum, replaces the binary, and re-execs
• Remote — the platform sends a self_update command when a new version is published; the agent auto-restarts under systemd on success

The agent version and update-check state are visible on the server detail page.

Requirements

• Linux (amd64 or arm64)
• systemd
• ~10-15 MB resident memory in steady-state
• Outbound HTTPS to api.hostatlas.app, install.hostatlas.app, ip.hostatlas.app

Currently no Windows or macOS builds — the agent is Linux-server-focused.

Uninstall

sudo systemctl stop hostatlas-agent
sudo systemctl disable hostatlas-agent
sudo rm -rf /etc/hostatlas /var/lib/hostatlas /var/log/hostatlas
sudo rm /etc/systemd/system/hostatlas-agent.service
sudo rm /usr/local/bin/hostatlas-agent
sudo systemctl daemon-reload

The server can then be removed from the HostAtlas dashboard via Servers → the server → Delete (queued deletion — see the platform’s Servers page).

Security

• Agent token authentication on every push (Authorization: Bearer <token>)
• TLS 1.3 minimum on all outbound HTTPS
• No SSH keys stored, generated, or synced by the agent
• Public-IP filtering — CGNAT (100.64.0.0/10) and Tailscale ranges are excluded from what the agent reports as its public IP, so the wrong address never lands in the dashboard
• Sensitive-config filtering — SSL keys, credentials, secrets stripped from nginx/apache config before transmission
• Cron sanitization — passwords/tokens/secrets in cron entries masked before upload

Related

• Getting Started → Install the Agent — install walkthrough with distro-specific notes
• Servers — what the agent’s data looks like in the dashboard
• Server CLI — pairs with the agent for on-server recipe execution
• Backup CLI — independent backup tool that runs alongside (or without) the agent