The HostAtlas agent is a small Go binary that runs as a systemd service. It is open-source and self-contained — no runtime dependencies beyond standard system tools.

Supported distributions

• Ubuntu 20.04, 22.04, 24.04
• Debian 11, 12
• CentOS Stream 9
• RHEL 8, 9
• Fedora 39+

Both amd64 and arm64 architectures are supported.

One-liner install

Grab your install key from Settings → Install Keys in the platform, then run:

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

The installer will:

1. Detect your OS and architecture
2. Download the matching agent binary to /opt/hostatlas/hostatlas-agent
3. Write a config file at /etc/hostatlas/agent.yaml containing your install key and the platform endpoint
4. Register and start a systemd unit (hostatlas-agent.service)
5. Trigger the first discovery pass

Note

The installer requires sudo. The agent itself runs as root so it can read protected log files, inspect firewall state, and run privileged discovery. All outbound traffic is a single authenticated HTTPS connection to api.hostatlas.app.

Install keys

Install keys are rotating credentials scoped to your organization. Create multiple keys if you want to revoke one later without re-installing everywhere (e.g. one per environment, one per team).

Find them at Settings → Install Keys. Each key shows the number of active agents using it and the last-seen timestamp.

Verification

After the installer finishes, confirm the agent is running:

systemctl status hostatlas-agent

Expected output:

● hostatlas-agent.service - HostAtlas Agent
     Loaded: loaded (/etc/systemd/system/hostatlas-agent.service; enabled)
     Active: active (running)

Live logs:

journalctl -u hostatlas-agent -f

Within about 30 seconds the host should appear in the dashboard under Servers.

Common operations

Restart

sudo systemctl restart hostatlas-agent

Stop

sudo systemctl stop hostatlas-agent

Status

systemctl status hostatlas-agent

Logs

journalctl -u hostatlas-agent -f

Uninstall

The installer ships an uninstall script alongside the binary:

sudo /opt/hostatlas/uninstall.sh

This stops and disables the systemd service, removes /opt/hostatlas/ and /etc/hostatlas/, and sends a final deregistration event so the server disappears cleanly from the dashboard.

Caution

Uninstalling is irreversible for that host — metrics history is retained in the platform, but the server will be marked inactive. Re-installing later creates a new server record.

Troubleshooting

If the server does not show up within a minute:

• Check outbound HTTPS reachability: curl -I https://api.hostatlas.app
• Confirm the install key in /etc/hostatlas/agent.yaml matches what you see in the dashboard
• Look for auth errors in journalctl -u hostatlas-agent

Need more help? Email support or run hostatlas doctor from the CLI against the same host.